Skip to main content
POST
Start a knowledge base upload
Reserves a slot in an agent’s knowledge base and returns a presigned URL to upload the file to.

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.
1

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.
2

Upload the file

PUT the raw file bytes to uploadUrl, sending Content-Type exactly as returned in contentType.
Do not send your API key with this request. The upload URL carries its own authorisation, and adding an Authorization header will cause storage to reject the upload.
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.
3

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

A reserved slot counts against the per-agent document limit even before the file is uploaded. If you abandon an upload, the slot is released automatically after 24 hours — or immediately, if you 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. A 429 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-After seconds

Authorizations

Authorization
string
header
required

API key for authentication using Bearer scheme

Path Parameters

id
string<uuid>
required

Agent the knowledge base belongs to.

Query Parameters

companyId
string

Required for ATS API keys to specify which company to access. Ignored for standard company API keys.

Body

application/json
fileName
string
required

Name of the file being uploaded, including its extension.

Maximum string length: 255
Example:

"benefits-and-perks.pdf"

mimeType
enum<string>
required

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.

Available options:
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
Example:

"application/pdf"

sizeBytes
integer
required

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.

Required range: 1 <= x <= 20971520
Example:

482133

title
string

Human-readable label for the document. Defaults to fileName.

Maximum string length: 255
Example:

"Benefits and perks"

Response

Slot reserved and upload URL issued

document
object
required

The reserved document, in PENDING state until the upload is completed.

uploadUrl
string
required

Presigned storage URL to PUT the file to. Carries its own authorisation — do not send your API key with it.

Example:

"https://instaview-agent-knowledge-production.s3.eu-central-1.amazonaws.com/agent-knowledge/..."

uploadMethod
enum<string>
required

HTTP method the upload URL expects.

Available options:
PUT
Example:

"PUT"

contentType
string
required

The Content-Type header the PUT must send. It is part of the URL's signature, so any other value is rejected by storage.

Example:

"application/pdf"

expiresAt
string<date-time>
required

When the upload URL stops working. The document slot outlives it — request a new upload if this expires.

Example:

"2026-08-08T10:30:00.000Z"

maxBytes
number
required

Maximum bytes the stored object may have. A larger file is rejected at completion and deleted.

Example:

20971520