Start Knowledge Upload
Reserves a document slot on the agent and returns a presigned URL to upload the file to. The file never passes through this API.
POSTthis endpoint with the file’s name, MIME type and size.PUTthe raw file bytes to the returneduploadUrl, sendingContent-Typeexactly as returned incontentType. Do not send your API key with this request — the URL carries its own authorisation.POST /agents/{id}/knowledge/{documentId}/completeto confirm the upload.
The document stays PENDING, and is never used on a call, until step 3 succeeds. Uploads that are never completed are cleaned up automatically after 24 hours and release the slot they held.
This endpoint has a lower rate limit than the rest of the API.
Overview
A knowledge base is a set of documents the agent can look up mid-call — a job spec, a benefits summary, a pricing sheet, an FAQ. Attaching one is a three-step flow, because the file bytes go straight to storage and never pass through this API.Reserve a slot
POST /agents/{id}/knowledge with the file’s name, MIME type and size. You get back a documentId and an uploadUrl.sizeBytes must be the file’s exact byte count, not an estimate. Both it and the MIME type are signed into the upload URL.Upload the file
PUT the raw file bytes to uploadUrl, sending Content-Type exactly as returned in contentType.Storage rejects the PUT with 403 if the Content-Type or the Content-Length differs from what was signed — so a file whose real size does not match the sizeBytes you declared will not upload. Most HTTP clients set Content-Length for you from the body.Complete the upload
POST /agents/{id}/knowledge/{documentId}/complete. The stored file is verified, and only then does the document become usable on calls.Example
Supported File Types
PDF, DOC, DOCX, TXT, MD, CSV, TSV, JSON, XML and YAML. Files are stored in the format you upload them in — there is no conversion step, so nothing is lost in translation.Limits
DELETE the document.Rate Limiting
This endpoint has a lower rate limit than the rest of the API — 6 requests per minute and 60 per hour, per API key — because each call reserves a document slot and, once completed, a stored file. A429 response carries a Retry-After header with the number of seconds to wait. Completing an upload is limited separately and more generously, so retrying a failed completion is cheap.
Error Scenarios
- 400 Bad Request: Unsupported file type, a size over 20 MB, or the agent already holds 10 documents
- 404 Not Found: No agent with that id belongs to your API key’s company
- 429 Too Many Requests: Upload rate limit exceeded — wait for
Retry-Afterseconds
Related Resources
Authorizations
API key for authentication using Bearer scheme
Path Parameters
Agent the knowledge base belongs to.
Query Parameters
Required for ATS API keys to specify which company to access. Ignored for standard company API keys.
Body
Name of the file being uploaded, including its extension.
255"benefits-and-perks.pdf"
MIME type of the file. The returned upload URL is signed for this exact type, so the PUT must send it back as its Content-Type header verbatim.
application/pdf, application/msword, application/vnd.openxmlformats-officedocument.wordprocessingml.document, text/plain, text/markdown, text/csv, text/tab-separated-values, application/json, application/xml, text/xml, application/yaml, text/yaml "application/pdf"
Exact size of the file in bytes. This is binding, not an estimate: it is signed into the upload URL, so the PUT must send precisely this many bytes and storage rejects anything else with a 403. Send the real byte count of the file you are about to upload; most HTTP clients set Content-Length for you from the body. Checked again against the stored object at completion.
1 <= x <= 20971520482133
Human-readable label for the document. Defaults to fileName.
255"Benefits and perks"
Response
Slot reserved and upload URL issued
The reserved document, in PENDING state until the upload is completed.
Presigned storage URL to PUT the file to. Carries its own authorisation — do not send your API key with it.
"https://instaview-agent-knowledge-production.s3.eu-central-1.amazonaws.com/agent-knowledge/..."
HTTP method the upload URL expects.
PUT "PUT"
The Content-Type header the PUT must send. It is part of the URL's signature, so any other value is rejected by storage.
"application/pdf"
When the upload URL stops working. The document slot outlives it — request a new upload if this expires.
"2026-08-08T10:30:00.000Z"
Maximum bytes the stored object may have. A larger file is rejected at completion and deleted.
20971520