Knowledge
Push, update and delete documents from your server, set tenants and access rules, and track indexing status.
Your server pushes documents and records into a knowledge base by external id. Every endpoint on this page is server to server and uses a server token with purpose kb_write. See Authentication.
{kbId} is the knowledge base's id from the console. It must belong to the agent's organization, or you get 404 knowledge_base_not_found. An id that does not exist looks the same.
Pushes are limited per secret key to 1,000 items a minute. A batch of 100 counts as 100. Over the limit you get 429 rate_limited with Retry-After.
@baseera/node wraps all of this: createBaseera({ agentId, secretKey, baseUrl }).kb has upsert, upsertMany, delete, status and createTenantUploadToken. It signs a fresh token for every call.
Push items
POST /v0/knowledge/{kbId}/items
The body is { "items": [...] } with 1 to 100 items and at most 4,000,000 bytes. A body over the size is 413 message_too_large. A body that is not { items }, or has 0 or more than 100 items, is 400 invalid_request.
Each item:
Prop
Type
Unknown fields are rejected. Metadata is stored on the item and on each chunk under meta, but it is not searched or filtered yet.
Signing the token needs code, so mint it first and pass it in:
curl -X POST "$BASEERA_URL/v0/knowledge/$KB_ID/items" \
-H "x-baseera-agent: $BASEERA_AGENT_ID" \
-H "x-baseera-server-token: $SERVER_TOKEN" \
-H "content-type: application/json" \
-d '{
"items": [
{
"externalId": "refund-policy",
"title": "Refund policy",
"text": "Refunds take five days after approval.",
"metadata": { "lang": "en", "tags": ["policy", "billing"], "version": 3 },
"tenantId": "acme"
}
]
}'Response, 200 OK, one result per item in the order sent. One bad item is rejected and never fails the others:
{
"results": [
{ "externalId": "refund-policy", "status": "queued" },
{ "externalId": "shipping", "status": "unchanged" },
{ "externalId": "x", "status": "rejected", "error": { "code": "invalid_item", "message": "title must be 1 to 300 characters." } }
]
}| Status | Meaning |
|---|---|
queued | A new version is on its way. It becomes searchable when ready. |
unchanged | Content, title and metadata hash to what is already indexed or queued. Nothing was written or embedded. |
rejected | The item failed. See the codes below. |
Rejection codes: invalid_item, too_large, limit_reached (20,000 pushed items per knowledge base, or the organization's storage), not_found (an uploadId that is not this item's, or whose bytes were not uploaded), conflict (a newer version was pushed meanwhile), unavailable (storage failed, send it again).
Replacing an item
A changed item keeps its source (same id, version plus one) and is processed again. A new version is searchable only once it is ready. Until then, the previous version keeps answering under the rules it was published with.
The content hash is the SHA-256 of the normalized content (NFC, LF line endings, trimmed), the title and the metadata with keys in order. A url item is always fetched again. If the page is byte-identical, the indexed chunks are kept and nothing is embedded.
Files
A document is never sent through the JSON body. Reserve a signed upload first.
POST /v0/knowledge/{kbId}/uploads
{
"items": [
{
"externalId": "handbook",
"title": "Employee handbook",
"fileName": "handbook.pdf",
"mimeType": "application/pdf",
"bytes": 482113,
"sha256": "9b74c9897bac770ffc029102a200c5de..."
}
]
}Up to 20 items. Files may be PDF, DOCX, Markdown, TXT, HTML or CSV, at most 50 MB, with a mimeType that matches the extension. sha256 (hex of the file's bytes) lets Baseera answer unchanged without an upload. metadata, tenantId and access are also accepted.
Response:
{ "results": [ { "externalId": "handbook", "status": "upload", "uploadId": "upl_01H...", "uploadUrl": "https://..." } ] }A result can also be unchanged or rejected.
Upload the bytes
PUT the file to uploadUrl with Content-Type set to the mimeType, and no Baseera headers. The URL is one-time, for that one object path, valid for a short time, and can neither read nor overwrite.
Finish the item
Push { "externalId", "title", "uploadId", "tenantId"? } to the items endpoint. Baseera checks the object exists with the declared size and queues it.
Send access in the upload reservation, not with the uploadId. Rules in the reservation apply even when the file is unchanged.
Fetched addresses
A url item is fetched by Baseera's worker with these protections:
- https only, no credentials in the address, port 443 or 1024 and up.
- Baseera resolves the name, and every address must be public. Loopback, private, link-local (including the cloud metadata address), carrier-grade NAT, multicast, reserved and documentation ranges are refused, for IPv4 and IPv6, including IPv4-mapped, NAT64 and 6to4 forms. The connection goes to the checked address.
- At most 3 redirects, each checked again.
- No cookies and no
Authorizationheader. - At most 20 MB and 20 seconds. Only HTML, plain text, Markdown, CSV, PDF and DOCX.
A refused or failing address fails the source with blocked_url or fetch_failed, which a webhook reports.
Indexing status
GET /v0/knowledge/{kbId}/items/{externalId}?tenantId=
curl "$BASEERA_URL/v0/knowledge/$KB_ID/items/refund-policy?tenantId=acme" \
-H "x-baseera-agent: $BASEERA_AGENT_ID" \
-H "x-baseera-server-token: $SERVER_TOKEN"{
"externalId": "refund-policy",
"status": "ready",
"version": 2,
"errorCode": null,
"chunkCount": 4,
"updatedAt": "2026-11-11T10:00:00.000Z",
"processedAt": "2026-11-11T10:00:04.000Z"
}status is one of pending_upload, queued, parsing, embedding, ready, failed. No content is returned. An unknown item is 404 source_not_found. The external id in the path is URL-encoded. Use ?tenantId= for an item pushed with a tenant, because the same id with and without a tenant are two items.
Instead of polling, use a webhook for knowledge.item.ready and knowledge.item.failed.
Delete an item
DELETE /v0/knowledge/{kbId}/items/{externalId}?tenantId=
Removes the item, its chunks and its original, and logs the deletion (the key's id, no content).
{ "deleted": true }Deleting something that is not there answers { "deleted": false }.
Tenants
tenantId scopes an item to one of your customers. A session sees platform-wide chunks (no tenant) plus its own tenant's chunks, never another tenant's. The tenant comes only from the verified user token.
Purge a tenant
DELETE /v0/knowledge/tenants/{tenantId}, with a server token of purpose purge_knowledge.
Deletes every source, document, chunk and embedding with that tenant id in the agent's organization, across all knowledge bases. Knowledge with no tenant and other tenants are not touched. The body must repeat the id, so a wrong URL deletes nothing:
{ "confirm": "acme" }Without it you get 400 invalid_request. The tenant id in the path is URL-encoded. The response is the confirmation record, also written to the organization's deletion log (ids and counts, no names or content):
{ "id": "...", "tenantId": "acme", "sources": 3, "chunks": 142, "requestedAt": "2026-11-10T10:00:00Z", "completedAt": "2026-11-10T10:00:01Z" }completedAt is when the database work finished and the sources stopped being searchable. The original files are removed from storage within about a minute. Purging a tenant with nothing stored returns 200 with zero counts. @baseera/node has purgeTenantKnowledge.
Access rules
A source can carry rules that say which users may find it. access maps a claim name to the values that qualify:
{ "roles": ["staff", "admin"], "plan": ["pro"] }That is met by a user whose token has a roles value of staff or admin and a plan value of pro. The token's role counts as a roles value (and as role). Every other name comes from the token's claims. See User tokens.
Limits: at most 10 names, 1 to 20 values each (1 to 100 characters), 2 KB in all. Matching is exact and case-sensitive.
- Fail closed. An item with rules is invisible to a user whose token lacks the claim. An item with no rules is visible to everyone. A token with no
roleand noclaimssees only items without rules. An empty or unreadable rule matches nobody. - Enforced in the database query, before ranking and before the result limit. A restricted passage cannot reach the model, the answer, a citation or a source link of a user who does not qualify. Nothing in a response says that a restricted item exists.
- Claims come only from the verified user token. A chat request body, the model and tools cannot set them.
- Versions. Until a new version is
ready, the previous version answers under its own rules. A stricter rule applies at once, a wider one when the new version is ready.
Tenant uploads
Admins of your tenants can add documents that only their tenant's users get answers from. Your server decides who may. The browser only carries the proof.
The setting knowledge.tenantUploads is off by default. While it is off, every endpoint below answers 403 tenant_uploads_disabled. The knowledge base must also be attached to the agent.
Sign an upload token on your server
Use createBaseera(...).kb.createTenantUploadToken or signTenantUploadToken. It is a server token with purpose kb_tenant_upload and claims kb, tid and uid. It is valid 5 minutes by default and at most 10.
Call the upload endpoints from the browser
Send the token in x-baseera-upload-token, with the publishable key, from an allowed origin. The tenant, knowledge base and user come only from the token. A missing, expired, foreign or wrong-purpose token is 401 invalid_server_token.
| Method and path | Purpose |
|---|---|
POST /v0/tenant-knowledge/uploads | Body { fileName, mimeType, bytes, sha256? }. Returns { "status": "upload", "uploadId", "uploadUrl" } or { "status": "unchanged" }. Files up to 25 MB. |
POST /v0/tenant-knowledge/uploads/confirm | Body { "uploadId": "upl_..." }. Checks the object and queues it. |
GET /v0/tenant-knowledge/sources | Returns { "sources": [ { id, name, status, errorCode, bytes, version, updatedAt } ] } for the token's tenant only. |
DELETE /v0/tenant-knowledge/sources/{sourceId} | Removes one of the tenant's own uploads. 200 { "ok": true }, else 404 source_not_found. |
Quotas per tenant and knowledge base: 200 files, 200 MB in all, 25 MB a file (413 knowledge_quota_exceeded). Rate: 20 uploads a minute per user and 30 per tenant (429 rate_limited). Tenants cannot set access rules, and a tenant cannot replace an item you pushed.