Graine AI
API referenceKnowledge bases

Query a knowledge base

Retrieve from a knowledge base — the way to test what an agent will see.

Retrieve from a knowledge base — the way to test what an agent will see.

An agent using this knowledge base runs the same retrieval on every customer turn and prepends the matched text to its prompt, so what comes back here is what the agent gets. If this returns nothing, the agent will answer from its prompt alone and the call will sound completely normal — silent misses are exactly what this endpoint exists to make visible.

total_candidates counts what was retrieved BEFORE reranking, so with rerank: true it is larger than returned. score is 1/(1+distance), not a cosine similarity: it is useful for ordering, not as an absolute confidence.

The knowledge base is the one in the path, resolved against your organisation: this endpoint accepts no collection list, so it cannot be pointed at another organisation's knowledge base.

Rate limit: 1000 requests per minute per organization (bucket default). Exceeding it returns 429 with Retry-After; the X-RateLimit-* response headers report your remaining allowance on every call.

POST
/v2/knowledge-bases/{collection}/query
/v2/knowledge-bases/product-handbook/query

The Authorization access token

Authorization

Authorization
Required
Bearer <token>

Your Graine API key. Create one in the dashboard under Developers, or via POST /v2/api-keys. Send it as Authorization: Bearer <key>.

In: header

Request Body

application/jsonRequired

query
Required
Query

The text to retrieve against.

Minimum length: 1Maximum length: 4000

max_resultsMax Results

Chunks to retrieve before any reranking.

Default: 10Minimum: 1Maximum: 50

similarity_thresholdSimilarity Threshold

Minimum score to keep. Scores are 1/(1+distance), so 0.0 (the default) keeps everything and values above ~0.5 are aggressive.

Default: 0Minimum: 0Maximum: 1

rerankRerank

Re-order candidates with a cross-encoder. Slower, more precise.

Default: false

rerank_candidatesRerank Candidates

Candidates fed to the reranker when rerank is true.

Default: 20Minimum: 1Maximum: 100

rerank_finalRerank Final

Chunks kept after reranking when rerank is true.

Default: 5Minimum: 1Maximum: 50

Path Parameters

collection
Required
Collection

The knowledge base name.

Query Parameters

organization_idOrganization Id

Must match the organisation the API key belongs to.

Response Body

200

The matched chunks, most relevant first.

collection
Required
Collection

The knowledge base that was queried.

documents
Required
Documents

Matched chunks, most relevant first.

returned
Required
Returned

Number of chunks in 'documents'.

total_candidates
Required
Total Candidates

Candidates retrieved BEFORE reranking. With rerank enabled this is larger than 'returned'; it is not a corpus-wide match count.

query_time_msQuery Time Ms | null

Upstream retrieval time.

400

1000 — malformed input (bad knowledge base name, unreadable or empty file).

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

401

1100 — missing, unknown or inactive API key. 1101 — a browser session token was presented.

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

403

1102 — the key is valid but lacks the scope this endpoint requires, or names another organisation. GET /v2/scopes reports which scopes the key holds.

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

404

1200 — no such knowledge base in this organisation. Cross-tenant reads answer 404, never 403.

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

422

1001 — the body or query failed validation; the message names the first offending field.

error
Required
integer

Stable integer code from the error table. Branch on this, not on the message.

message
Required
string

One human-readable sentence. Wording may change; the code will not.

429

1300 — per-organisation rate limit exceeded. Carries Retry-After.

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

503

1501 — the knowledge service is unreachable or returned a 5xx.

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

504

1502 — the knowledge service did not respond in time. A slow ingest may still complete.

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

curl -X POST "https://api.graine.ai/v2/knowledge-bases/product-handbook/query?organization_id=string" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What is the refund window?",
    "max_results": 10,
    "similarity_threshold": 0.35,
    "rerank": true,
    "rerank_candidates": 20,
    "rerank_final": 5
  }'

The matched chunks, most relevant first.

{
  "collection": "product-handbook",
  "documents": [
    {
      "text": "Installation is free on orders above 5,000; below that a flat 250 visit charge applies.",
      "score": 0.7787,
      "metadata": {
        "collection": "product-handbook",
        "file_name": "pricing-2026.pdf",
        "page_number": 12,
        "content_type": "text",
        "distance": 0.2841
      }
    }
  ],
  "returned": 5,
  "total_candidates": 20,
  "query_time_ms": 148.6
}

Previous

Add documents to a knowledge base POST

Next

Create a knowledge base POST