Graine AI
API referenceKnowledge bases

Add documents to a knowledge base

Add documents to an existing knowledge base.

Add documents to an existing knowledge base.

Send multipart/form-data with one or more files parts. The same limits and the same slow, synchronous ingest as POST /v2/knowledge-bases apply: 10 files, 25MB each, 50MB per request, PDF/PNG/JPG/JPEG only, up to 180 seconds.

A knowledge base that does not exist in your organisation answers 404 — create it with POST /v2/knowledge-bases first. Uploading a file that is already present adds a second copy of its chunks rather than replacing them, and there is no way to remove them, so check the documents list before re-uploading after a timeout.

Content-Length is required, and a second concurrent upload from the same organisation answers 429 with Retry-After.

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

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

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

multipart/form-dataRequired

files
Required
array<file>

The documents. Repeat the field once per file: PDF, PNG, JPG or JPEG, at most 10 files, 25MB each, 50MB per request.

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

201

What was indexed into the knowledge base.

collection
Required
Collection

The knowledge base the documents were added to.

retrieval_id
Required
Retrieval Id

The identifier to give an agent's rag_config.

files_accepted
Required
Files Accepted

File names that were ingested.

chunks_indexed
Required
Chunks Indexed

Text chunks created. Zero means nothing was extracted.

metadata_recorded
Required
Metadata Recorded

False when the documents were indexed but their metadata record failed to write: retrieval works, listings will not show them.

warnings
Required
Warnings

Non-fatal problems with this upload. Usually empty.

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.

409

1201 — that knowledge base name is not available, or it already exists.

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.

411

1000 — an upload arrived without Content-Length. Chunked uploads are not accepted.

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.

413

1000 — the upload exceeds the per-file or per-request size limit.

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.

415

1000 — a file is not a PDF, PNG, JPG or JPEG.

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/documents?organization_id=string" \
  -H "Authorization: Bearer <token>" \
  -F files="[\n  \"string\"\n]"

What was indexed into the knowledge base.

{
  "collection": "product-handbook",
  "retrieval_id": "internal_organization-live-EXAMPLE__product-handbook",
  "files_accepted": [
    "pricing-2026.pdf"
  ],
  "chunks_indexed": 84,
  "metadata_recorded": true,
  "warnings": []
}

Previous

List knowledge bases GET

Next

Query a knowledge base POST