Query the graph

Ask a question and get ranked passages from completed documents. Use this when you need retrieval for an evaluation harness or your own reader. Use Chat when you want a conversational answer with tools.

The samples read your key from the YGGY_API_KEY environment variable. Replace the host, organization id or slug, and project ID with values from your environment. The key needs graph:read. Create a key as described in Authentication.

Every parameter and response field is in the Reference.

Query one project

This sample asks whether two people share a nationality. The project already contains completed documents titled Scott Derrickson and Ed Wood.

curl --fail-with-body \
  --header "x-api-key: $YGGY_API_KEY" \
  --header "x-yggy-organization-id: acme-corp" \
  --header "content-type: application/json" \
  --data '{"question":"Were Scott Derrickson and Ed Wood of the same nationality?","topK":5,"mode":"hybrid"}' \
  "https://api.yggy.tech/api/v1/projects/0xproject/query"

A successful response has this form:

{
  "answer": "Scott Derrickson is an American director, screenwriter and producer.",
  "contexts": [
    {
      "id": "scott-derrickson",
      "documentId": "aa97cfc6-1111-4111-8111-aaaaaaaaaaaa",
      "source": "benchmark:scott-derrickson",
      "title": "Scott Derrickson",
      "snippet": "Scott Derrickson is an American director, screenwriter and producer.",
      "score": 1
    }
  ]
}

id is the document source when you set one (benchmark:scott-derrickson becomes scott-derrickson). Otherwise it is the document id. The answer is a short passage from the top context. It is empty when nothing matches.

Query the organization

Omit the project path to search every project the caller can access.

curl --fail-with-body \
  --header "x-api-key: $YGGY_API_KEY" \
  --header "x-yggy-organization-id: acme-corp" \
  --header "content-type: application/json" \
  --data '{"question":"Were Scott Derrickson and Ed Wood of the same nationality?","topK":5}' \
  "https://api.yggy.tech/api/v1/query"

The body and response match the project route.

Include graph matches

The default body stays { answer, contexts }. Add include when you need the matching entities, triples, or approved identity that ranked into those contexts.

curl --fail-with-body \
  --header "x-api-key: $YGGY_API_KEY" \
  --header "x-yggy-organization-id: acme-corp" \
  --header "content-type: application/json" \
  --data '{"question":"Were Scott Derrickson and Ed Wood of the same nationality?","topK":5,"mode":"hybrid","include":["entities","triples","identity"]}' \
  "https://api.yggy.tech/api/v1/projects/0xproject/query"

A successful response then also has this form:

{
  "answer": "Scott Derrickson is an American director, screenwriter and producer.",
  "contexts": [
    {
      "id": "scott-derrickson",
      "documentId": "aa97cfc6-1111-4111-8111-aaaaaaaaaaaa",
      "source": "benchmark:scott-derrickson",
      "title": "Scott Derrickson",
      "snippet": "Scott Derrickson is an American director, screenwriter and producer.",
      "score": 1
    }
  ],
  "entities": [
    {
      "uri": "https://id.yggy.tech/org/org_01JACME/entities/01JENTITY",
      "label": "Scott Derrickson",
      "type": "https://ontology.yggy.tech/classes/person",
      "score": 0.9,
      "documentIds": ["aa97cfc6-1111-4111-8111-aaaaaaaaaaaa"],
      "identity": {
        "namespaceUri": "https://www.wikidata.org/entity",
        "value": "Q123"
      }
    }
  ],
  "triples": [
    {
      "subject": {
        "uri": "https://id.yggy.tech/org/org_01JACME/entities/01JENTITY",
        "label": "Scott Derrickson"
      },
      "predicate": {
        "uri": "https://ontology.yggy.tech/properties/nationality",
        "label": "nationality"
      },
      "object": { "label": "American" },
      "evidence": "Scott Derrickson is an American director.",
      "documentId": "aa97cfc6-1111-4111-8111-aaaaaaaaaaaa"
    }
  ]
}

include accepts entities, triples, and identity. The route returns at most 20 entities and 20 triples, and only those that match a ranked context. Empty arrays mean you asked for that field and nothing matched. identity is present only when it is approved. include: ["identity"] alone returns only entities that have an approved identity. Entity and class uri values are public HTTPS URIs, never graph uids. Evidence is stored hit text; the route does not invent it from the document snippet.

Choose a mode

Mode	What it ranks
hybrid (default)	Document text plus matching graph labels
lexical	Document text only
graph	Documents that match graph labels only

topK is 1 to 20 and defaults to 5. The route reads at most 200 completed documents.

If the caller cannot access the project in the path, the status is 403. The body is either { "error": "Project access denied" } or an error with error.code PROJECT_DENIED, depending on which check refuses the request.