Quickstart

Make one REST call against your organization’s graph in a few minutes. You need a yggy account that is a member of the organization.

1. Create a personal key

1. In yggy, open Developers → API keys.
2. Under Your personal keys, choose Create key and name it, for example Quickstart.
3. Under Permissions, every area starts with Read checked. Keep only the narrowest set you need: Read under Documents and Knowledge Graph is enough here, and the query below needs graph:read.
4. Under Expiry, choose a short lifetime such as 30 days. The default is Never.
5. Copy the key and store it in a secret manager. yggy shows the full key only when you create it.

A personal key acts as you, with your project access. Authentication explains organization keys and permissions.

2. Export the key

Paste the key when the shell waits for it. It is not shown and does not end up in your shell history.

read -rs YGGY_API_KEY && export YGGY_API_KEY

3. Make the call

This asks a question across every project you can access. Replace acme-corp with your organization slug or id. If your organization runs yggy on its own servers, replace the host with its API host.

curl

curl --fail-with-body "https://api.yggy.tech/api/v1/query" \
  --header "Authorization: Bearer $YGGY_API_KEY" \
  --header "x-yggy-organization-id: acme-corp" \
  --header "content-type: application/json" \
  --data '{"question":"Which contracts renew in Q1?"}'

TypeScript

const res = await fetch("https://api.yggy.tech/api/v1/query", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.YGGY_API_KEY}`,
    "x-yggy-organization-id": "acme-corp",
    "content-type": "application/json",
  },
  body: JSON.stringify({"question":"Which contracts renew in Q1?"}),
});
console.log(await res.json());

Python

import os
import requests

res = requests.post(
    "https://api.yggy.tech/api/v1/query",
    headers={
        "Authorization": f"Bearer {os.environ['YGGY_API_KEY']}",
        "x-yggy-organization-id": "acme-corp",
    },
    json={"question":"Which contracts renew in Q1?"},
)
print(res.json())

A successful response has this form:

{
  "answer": "The Northwind supply contract renews on 15 January unless either party cancels in writing.",
  "contexts": [
    {
      "id": "aa97cfc6-1111-4111-8111-aaaaaaaaaaaa",
      "documentId": "aa97cfc6-1111-4111-8111-aaaaaaaaaaaa",
      "title": "Northwind supply contract.pdf",
      "snippet": "The Northwind supply contract renews on 15 January unless either party cancels in writing.",
      "score": 1
    }
  ]
}

answer is a short passage from the top context. It is empty when nothing matches. Query the graph shows how to ask one project, get more results and include graph matches.

4. Find the call in Usage and logs

Open Developers → Usage and logs. Your call is at the top of the list, with its status, response time and the key that made it. Select it to see its request ID. A failed call shows its error code and a hint, for example for a 401 or a 429. See Request logs and Errors and rate limits.

Handle errors

Check the HTTP status first. Then use error.code for program logic. Do not parse error.message.

{
  "success": false,
  "error": {
    "message": "You do not have permission to view documents.",
    "code": "FORBIDDEN"
  }
}

Where to go next

• Upload and extract a document, then read its facts.
• Browse every operation a key can call in the Reference.
• to inspect current paths and try a request. The OpenAPI document is at /openapi.json on the same host. Generate a client from the document of the environment your application calls, instead of copying samples into static types; the development API can change before a production release.
• Agents can start at /llms.txt on this docs site. /llms-small.txt and /llms-full.txt are the compact and complete variants. Each page has a markdown copy with a .md suffix (this page is /developers/quickstart.md).