Graine AI
API referenceKnowledge bases

Fetch one knowledge base

Fetch one knowledge base.

Fetch one knowledge base.

total_chunks counts indexed text chunks, not files: one PDF becomes many chunks. total_files counts a file once per upload, so re-uploading the same file increments it while files — which is distinct and sorted — stays the same length. Treat them as two different questions, not a pair.

A knowledge base belonging to another organisation answers 404, not 403: this API never confirms that another tenant's name exists.

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.

GET
/v2/knowledge-bases/{collection}
/v2/knowledge-bases/product-handbook

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

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 knowledge base, with its file list and chunk counts.

collection
Required
Collection

The knowledge base name you chose.

retrieval_id
Required
Retrieval Id

The identifier an agent retrieves with. To attach this knowledge base, PATCH the agent with configuration.runtime.language_model.knowledge_base_config.collections set to [retrieval_id]. It is the physical storage identifier: treat it as a secret of this organisation and do not put another organisation's value there.

total_chunks
Required
Total Chunks

Indexed text chunks across all uploads. NOT a file count.

total_files
Required
Total Files

Files counted across every upload, including a file uploaded more than once. It can therefore exceed the length of 'files'.

files
Required
Files

Distinct file names, sorted.

first_uploadFirst Upload | null

ISO-8601 UTC.

last_uploadLast Upload | null

ISO-8601 UTC.

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 GET "https://api.graine.ai/v2/knowledge-bases/product-handbook?organization_id=string" \
  -H "Authorization: Bearer <token>"

The knowledge base, with its file list and chunk counts.

{
  "collection": "handbook",
  "retrieval_id": "internal_organization-live-EXAMPLE__product-handbook",
  "total_chunks": 412,
  "total_files": 7,
  "files": [
    "faq.md",
    "pricing-2026.pdf",
    "product-handbook.pdf"
  ],
  "first_upload": "2026-08-20T13:06:01.724Z",
  "last_upload": "2026-08-26T10:48:18.239Z"
}

Previous

List a knowledge base's documents GET

Next

List knowledge bases GET