Create a knowledge base
Create a knowledge base by uploading its first documents.
Create a knowledge base by uploading its first documents.
Send multipart/form-data with a name field and one or more files
parts. The name is yours alone — another organisation using the same name
does not collide with, or block, yours.
Limits. At most 10 files per request, 25MB per file and 50MB in total. Only PDF, PNG, JPG and JPEG can be read; any other type is rejected with 415 rather than accepted and silently indexed as nothing.
This request is slow. Text extraction, OCR and embedding all happen
before it returns — seconds for a small PDF, minutes for a large scan. It is
allowed up to 180 seconds; a 504 means the ingest was still running, so
check GET /v2/knowledge-bases/{collection}/documents before retrying to
avoid indexing the same file twice.
Check the response. chunks_indexed: 0 means nothing readable was
found — usually a scan with no legible text. metadata_recorded: false
means retrieval will work but the upload will not appear in listings.
Anything of that kind is also spelled out in warnings.
Send Content-Length: an upload with no declared length is refused with
411 before any of it is read, and one larger than the total limit is refused
with 413 the same way. While an upload is being indexed, further uploads
from the same organisation answer 429 with Retry-After rather than
queueing behind it.
Adding documents later is POST /v2/knowledge-bases/{collection}/documents.
If the name already exists this returns 409; documents and knowledge bases
cannot be deleted.
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.
v2/knowledge-basesAuthorization
AuthorizationRequiredBearer <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-dataRequiredfilesRequiredarray<file>
The documents. Repeat the field once per file: PDF, PNG, JPG or JPEG, at most 10 files, 25MB each, 50MB per request.
nameRequiredstring
Name for the new knowledge base. 1-63 characters: letters, digits, dots and hyphens. Underscores are reserved.
Query Parameters
organization_idOrganization Id
Must match the organisation the API key belongs to.
Response Body
201
The created knowledge base and what was indexed into it.
collectionRequiredCollection
The knowledge base the documents were added to.
retrieval_idRequiredRetrieval Id
The identifier to give an agent's rag_config.
files_acceptedRequiredFiles Accepted
File names that were ingested.
chunks_indexedRequiredChunks Indexed
Text chunks created. Zero means nothing was extracted.
metadata_recordedRequiredMetadata Recorded
False when the documents were indexed but their metadata record failed to write: retrieval works, listings will not show them.
warningsRequiredWarnings
Non-fatal problems with this upload. Usually empty.
400
1000 — malformed input (bad knowledge base name, unreadable or empty file).
errorRequiredError
Stable integer code from the /v2 error table. Branch on this.
messageRequiredMessage
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.
errorRequiredError
Stable integer code from the /v2 error table. Branch on this.
messageRequiredMessage
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.
errorRequiredError
Stable integer code from the /v2 error table. Branch on this.
messageRequiredMessage
One human-readable sentence. Wording may change; the code will not.
409
1201 — that knowledge base name is not available, or it already exists.
errorRequiredError
Stable integer code from the /v2 error table. Branch on this.
messageRequiredMessage
One human-readable sentence. Wording may change; the code will not.
411
1000 — an upload arrived without Content-Length. Chunked uploads are not accepted.
errorRequiredError
Stable integer code from the /v2 error table. Branch on this.
messageRequiredMessage
One human-readable sentence. Wording may change; the code will not.
413
1000 — the upload exceeds the per-file or per-request size limit.
errorRequiredError
Stable integer code from the /v2 error table. Branch on this.
messageRequiredMessage
One human-readable sentence. Wording may change; the code will not.
415
1000 — a file is not a PDF, PNG, JPG or JPEG.
errorRequiredError
Stable integer code from the /v2 error table. Branch on this.
messageRequiredMessage
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.
errorRequiredinteger
Stable integer code from the error table. Branch on this, not on the message.
messageRequiredstring
One human-readable sentence. Wording may change; the code will not.
429
1300 — per-organisation rate limit exceeded. Carries Retry-After.
errorRequiredError
Stable integer code from the /v2 error table. Branch on this.
messageRequiredMessage
One human-readable sentence. Wording may change; the code will not.
503
1501 — the knowledge service is unreachable or returned a 5xx.
errorRequiredError
Stable integer code from the /v2 error table. Branch on this.
messageRequiredMessage
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.
errorRequiredError
Stable integer code from the /v2 error table. Branch on this.
messageRequiredMessage
One human-readable sentence. Wording may change; the code will not.
The created knowledge base and what was indexed into it.