Retrieve ranked documents across the organization

POST

/api/v1/query

curl --request POST \
  --url https://api.yggy.tech/api/v1/query \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "question": "example", "topK": 5, "mode": "hybrid", "include": [ "entities" ], "includeArchived": false }'

• Production

Return ranked document contexts for a question across every project the caller can access. Same body as the project query, including optional include.

Authorizations

• bearerAuth

Parameters

Header Parameters

host

string | null

x-yggy-organization-id

string | null

Request Body

Media type application/json

object

question

required

Natural-language question to retrieve documents for

string

>= 1 characters <= 2000 characters

topK

Maximum number of ranked contexts to return

integer

default: 5 >= 1 <= 20

mode

Hybrid combines document text with graph matches; lexical uses document text only; graph uses graph matches only

string

default: hybrid

Allowed values: hybrid lexical graph

include

Optional graph fields to attach. Omit for the default retrieve body. identity alone returns only entities with an approved identity.

Array<string>

<= 3 items

Allowed values: entities triples identity

includeArchived

Also search cold triples. Archived hits surface separately and trigger a background promote. Single-project scope only.

boolean

Responses

200

Ranked contexts and an extractive answer

Media type application/json

object

answer

required

Short extractive answer from the top context. Empty when nothing was retrieved.

string

contexts

required

Array<object>

object

id

required

Stable context id: source slug when present, otherwise the document id

string

documentId

required

Document id

string

source

Caller-supplied source id when the document has one

string

title

required

Document title

string

snippet

required

Short passage used for ranking

string

score

required

Relative rank from 0 to 1 inside this result set

number

entities

Present when include asks for entities or identity

Array<object>

object

uri

Public entity URI. Never a graph uid.

string

label

required

string

type

Public class URI

string

score

required

number

documentIds

required

Ranked context document ids this entity matched

Array<string>

identity

object

namespaceUri

required

Approved identity namespace, for example a Wikidata entity prefix

string

value

required

Value in that namespace

string

triples

Present when include asks for triples

Array<object>

object

subject

required

object

uri

Public HTTPS URI when one is stored

string

label

required

string

predicate

required

object

uri

Public HTTPS URI when one is stored

string

label

required

string

object

required

object

uri

Public HTTPS URI when one is stored

string

label

required

string

evidence

Stored hit text. Omitted when the graph hit has none.

string

documentId

string

archivedHits

Present when includeArchived was requested on a single project

Array<object>

object

tripleKey

required

string

text

required

Verbalized cold fact, e.g. subject predicate object

string

score

required

number

Example ^generated

{
  "answer": "example",
  "contexts": [
    {
      "id": "example",
      "documentId": "example",
      "source": "example",
      "title": "example",
      "snippet": "example",
      "score": 1
    }
  ],
  "entities": [
    {
      "uri": "example",
      "label": "example",
      "type": "example",
      "score": 1,
      "documentIds": [
        "example"
      ],
      "identity": {
        "namespaceUri": "example",
        "value": "example"
      }
    }
  ],
  "triples": [
    {
      "subject": {
        "uri": "example",
        "label": "example"
      },
      "predicate": {
        "uri": "example",
        "label": "example"
      },
      "object": {
        "uri": "example",
        "label": "example"
      },
      "evidence": "example",
      "documentId": "example"
    }
  ],
  "archivedHits": [
    {
      "tripleKey": "example",
      "text": "example",
      "score": 1
    }
  ]
}

400

Invalid request or usage limit exceeded

Media type application/json

object

success

required

boolean

error

required

object

message

required

string

code

required

string

Allowed values: INTERNAL_ERROR VALIDATION_ERROR UNAUTHORIZED RATE_LIMITED ORG_REQUIRED FORBIDDEN NOT_FOUND CONFLICT PROJECT_DENIED USAGE_LIMIT_EXCEEDED HUGINN_ERROR HUGINN_STREAM_ERROR QUERY_FAILED PROVIDER_CONFLICT PROVIDER_CONFIG_INVALID PROVIDER_NOT_CONNECTED PROVIDER_RATE_LIMITED PROJECT_MEMBER_USER_NOT_IN_ORG PROJECT_MEMBER_UNKNOWN_ROLE PROJECT_MEMBER_LAST_OWNER PROJECT_CONFLICT STORAGE_NOT_CONFIGURED BILLING_NOT_CONFIGURED LICENSE_INACTIVE PLAN_REQUIRED MEMBER_LIMIT_REACHED SAGA_ASK_QUOTA_EXCEEDED SAGA_ASK_RATE_LIMITED SAGA_ASK_BUSY SAGA_ASK_PAUSED SAGA_ASK_UPSTREAM SAGA_DICTATION_BUSY SAGA_DICTATION_UNAVAILABLE SAGA_SHARE_LINK_LIMIT PROJECT_MEMBERSHIP_JWT_TOO_LARGE WEBHOOK_URL_INVALID WEBHOOK_ADDRESS_BLOCKED WEBHOOK_EVENT_UNKNOWN WEBHOOK_ENDPOINT_LIMIT WEBHOOK_ENDPOINT_DISABLED WEBHOOK_DELIVERY_IN_PROGRESS ORG_KEY_PERSONAL_SCOPE API_KEY_PERMISSION_EXCEEDS_ROLE API_KEY_NO_PERMISSIONS ORG_KEY_GRAPH_SCOPE_UNAVAILABLE ORG_KEY_TOO_MANY_PROJECTS SENDER_IS_LOGIN_EMAIL SENDER_TAKEN

details

Example

{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR"
  }
}

401

Authentication required

Media type application/json

object

success

required

boolean

error

required

object

message

required

string

code

required

string

Allowed values: INTERNAL_ERROR VALIDATION_ERROR UNAUTHORIZED RATE_LIMITED ORG_REQUIRED FORBIDDEN NOT_FOUND CONFLICT PROJECT_DENIED USAGE_LIMIT_EXCEEDED HUGINN_ERROR HUGINN_STREAM_ERROR QUERY_FAILED PROVIDER_CONFLICT PROVIDER_CONFIG_INVALID PROVIDER_NOT_CONNECTED PROVIDER_RATE_LIMITED PROJECT_MEMBER_USER_NOT_IN_ORG PROJECT_MEMBER_UNKNOWN_ROLE PROJECT_MEMBER_LAST_OWNER PROJECT_CONFLICT STORAGE_NOT_CONFIGURED BILLING_NOT_CONFIGURED LICENSE_INACTIVE PLAN_REQUIRED MEMBER_LIMIT_REACHED SAGA_ASK_QUOTA_EXCEEDED SAGA_ASK_RATE_LIMITED SAGA_ASK_BUSY SAGA_ASK_PAUSED SAGA_ASK_UPSTREAM SAGA_DICTATION_BUSY SAGA_DICTATION_UNAVAILABLE SAGA_SHARE_LINK_LIMIT PROJECT_MEMBERSHIP_JWT_TOO_LARGE WEBHOOK_URL_INVALID WEBHOOK_ADDRESS_BLOCKED WEBHOOK_EVENT_UNKNOWN WEBHOOK_ENDPOINT_LIMIT WEBHOOK_ENDPOINT_DISABLED WEBHOOK_DELIVERY_IN_PROGRESS ORG_KEY_PERSONAL_SCOPE API_KEY_PERMISSION_EXCEEDS_ROLE API_KEY_NO_PERMISSIONS ORG_KEY_GRAPH_SCOPE_UNAVAILABLE ORG_KEY_TOO_MANY_PROJECTS SENDER_IS_LOGIN_EMAIL SENDER_TAKEN

details

Example

{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR"
  }
}

403

Project access denied

Media type application/json

object

success

required

boolean

error

required

object

message

required

string

code

required

string

Allowed values: INTERNAL_ERROR VALIDATION_ERROR UNAUTHORIZED RATE_LIMITED ORG_REQUIRED FORBIDDEN NOT_FOUND CONFLICT PROJECT_DENIED USAGE_LIMIT_EXCEEDED HUGINN_ERROR HUGINN_STREAM_ERROR QUERY_FAILED PROVIDER_CONFLICT PROVIDER_CONFIG_INVALID PROVIDER_NOT_CONNECTED PROVIDER_RATE_LIMITED PROJECT_MEMBER_USER_NOT_IN_ORG PROJECT_MEMBER_UNKNOWN_ROLE PROJECT_MEMBER_LAST_OWNER PROJECT_CONFLICT STORAGE_NOT_CONFIGURED BILLING_NOT_CONFIGURED LICENSE_INACTIVE PLAN_REQUIRED MEMBER_LIMIT_REACHED SAGA_ASK_QUOTA_EXCEEDED SAGA_ASK_RATE_LIMITED SAGA_ASK_BUSY SAGA_ASK_PAUSED SAGA_ASK_UPSTREAM SAGA_DICTATION_BUSY SAGA_DICTATION_UNAVAILABLE SAGA_SHARE_LINK_LIMIT PROJECT_MEMBERSHIP_JWT_TOO_LARGE WEBHOOK_URL_INVALID WEBHOOK_ADDRESS_BLOCKED WEBHOOK_EVENT_UNKNOWN WEBHOOK_ENDPOINT_LIMIT WEBHOOK_ENDPOINT_DISABLED WEBHOOK_DELIVERY_IN_PROGRESS ORG_KEY_PERSONAL_SCOPE API_KEY_PERMISSION_EXCEEDS_ROLE API_KEY_NO_PERMISSIONS ORG_KEY_GRAPH_SCOPE_UNAVAILABLE ORG_KEY_TOO_MANY_PROJECTS SENDER_IS_LOGIN_EMAIL SENDER_TAKEN

details

Example

{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR"
  }
}