Knowledge API

Manage documents within knowledge bases programmatically. Upload, update, retrieve metadata, and delete documents.

Required scope: knowledge-management

Prerequisite: Knowledge bases are created in the platform dashboard. See Knowledge Bases. This API manages documents within existing knowledge bases.

Document Upload Flow

Uploading a document requires three steps:

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  1. Request     │     │  2. Upload      │     │  3. Complete    │     │  4. Poll        │
│  Upload Link    │────▶│  File to S3     │────▶│  Upload         │────▶│  Status         │
└─────────────────┘     └─────────────────┘     └─────────────────┘     └─────────────────┘
        │                       │                       │                       │
        ▼                       ▼                       ▼                       ▼
   POST /upload-link      PUT to uploadUrl      POST /upload-complete    GET /documents
   Returns: uploadUrl,    Include headers       Returns: status          Check status
   uploadId, s3Key        from response         "pending"                until "ready"

1. Request upload link — Call /knowledge/documents/upload-link to get a pre-signed S3 URL

2. Upload file — PUT the file bytes to the returned uploadUrl with requiredHeaders

3. Complete upload — Call /knowledge/documents/upload-complete with the uploadId

4. Poll status — Query /knowledge/documents until status becomes ready or failed

Document Status Values

Status	Description
pending	Document uploaded, processing not yet started
processing	Document is being processed (text extraction, chunking, embedding)
ready	Document processed successfully and available for retrieval
failed	Processing failed; check error details

Document Identifiers

Documents can be referenced using two identifiers:

Identifier	Description
s3Key	System-generated path in format agents/<agentId>/<env>/<kbId>/<filename>. Returned by upload endpoints.
customDocumentId	Optional user-defined identifier. Use this to map documents to your external system IDs (e.g., CRM record ID, ticket ID). When provided during upload, you can use it instead of s3Key for update and delete operations.

Custom Metadata

The metadata field accepts arbitrary key-value pairs that you define. This is your custom metadata for filtering and organizing documents—not a predefined schema.

{
  "metadata": {
    "category": "policy",
    "locale": "en-US",
    "version": "2.1",
    "department": "support"
  }
}

Use metadata to filter documents during retrieval (see Knowledge Base RAG API).

---

Endpoints

Method	Endpoint	Description
POST	/knowledge/documents/upload-link	Get pre-signed URL for new document
POST	/knowledge/documents/upload-complete	Finalize new document upload
POST	/knowledge/documents/update/upload-link	Get pre-signed URL to update document
POST	/knowledge/documents/update/upload-complete	Finalize document update
PATCH	/knowledge/documents/metadata	Update document metadata only
GET	/knowledge/documents	Get document metadata
DELETE	/knowledge/documents	Delete a document

---

Create Upload Link

POST /knowledge/documents/upload-link

Generate a pre-signed URL to upload a new document.

Request Body

Field	Type	Required	Description
agentId	string	Yes	Agent UUID
environment	string	Yes	development, staging, or production
knowledgeBaseId	string	Yes	Knowledge base UUID
fileName	string	Yes	File name with extension (e.g., policy.pdf). If .zip, triggers batch import.
name	string	No	Display name for the document
metadata	object	No	Custom key-value pairs for filtering
customDocumentId	string	No	Your external identifier for this document

Request Example

{
  "agentId": "your-agent-id",
  "environment": "production",
  "knowledgeBaseId": "kb-abc123",
  "fileName": "refund-policy.pdf",
  "name": "Refund Policy",
  "metadata": {
    "category": "policy",
    "locale": "en"
  },
  "customDocumentId": "DOC-12345"
}

Response

{
  "uploadId": "upload-uuid",
  "uploadUrl": "https://s3.amazonaws.com/...",
  "expiresIn": 3600,
  "s3Key": "agents/agent-id/production/kb-abc123/refund-policy.pdf",
  "documentId": "document-uuid",
  "requiredHeaders": {
    "Content-Type": "application/pdf"
  }
}

Response Fields

Field	Type	Description
uploadId	string	Unique identifier for this upload session
uploadUrl	string	Pre-signed S3 URL for file upload (expires per expiresIn)
expiresIn	number	Seconds until uploadUrl expires
s3Key	string	Document path in storage; use for subsequent operations
documentId	string	System-generated document UUID
requiredHeaders	object	Headers to include when uploading to uploadUrl

Uploading the File

After receiving the response, upload your file:

curl -X PUT "<uploadUrl>" \
  -H "Content-Type: application/pdf" \
  --data-binary @refund-policy.pdf

---

Complete Upload

POST /knowledge/documents/upload-complete

Finalize the upload and trigger document processing.

Request Body

Field	Type	Required	Description
uploadId	string	Yes	The uploadId from upload-link response

Request Example

{
  "uploadId": "upload-uuid"
}

Response (Document)

{
  "type": "document",
  "s3Key": "agents/agent-id/production/kb-abc123/refund-policy.pdf",
  "documentId": "document-uuid",
  "name": "Refund Policy",
  "createdAt": "2026-01-15T12:00:00.000Z",
  "updatedAt": "2026-01-15T12:00:00.000Z",
  "status": "pending"
}

Response (ZIP Import)

When fileName ends with .zip, the response indicates a batch import job:

{
  "type": "zip_import",
  "zipJobId": "job-uuid",
  "status": "Pending",
  "s3Key": "agents/agent-id/production/kb-abc123/archive.zip"
}

Response Fields

Field	Type	Description
type	string	document for single files, zip_import for archives
s3Key	string	Document path in storage
documentId	string	Document UUID (for document type)
zipJobId	string	Import job UUID (for zip_import type)
name	string	Document display name
status	string	Processing status (see Status Values)
createdAt	string	ISO 8601 creation timestamp
updatedAt	string	ISO 8601 last update timestamp

---

Create Update Upload Link

POST /knowledge/documents/update/upload-link

Generate a pre-signed URL to replace an existing document's content.

Request Body

Field	Type	Required	Description
agentId	string	Yes	Agent UUID
environment	string	Yes	development, staging, or production
knowledgeBaseId	string	Yes	Knowledge base UUID
s3Key	string	*	Document path to update. Required if customDocumentId not provided.
customDocumentId	string	*	Your external document ID. Required if s3Key not provided.
fileName	string	Yes	New file name
metadata	object	No	Updated custom metadata (replaces existing)

Note: Provide either s3Key or customDocumentId, not both.

Request Example

{
  "agentId": "your-agent-id",
  "environment": "production",
  "knowledgeBaseId": "kb-abc123",
  "customDocumentId": "DOC-12345",
  "fileName": "refund-policy-v2.pdf",
  "metadata": {
    "category": "policy",
    "locale": "en",
    "version": "2.0"
  }
}

Response

{
  "uploadId": "upload-uuid",
  "uploadUrl": "https://s3.amazonaws.com/...",
  "expiresIn": 3600,
  "s3Key": "agents/agent-id/production/kb-abc123/refund-policy-v2.pdf",
  "requiredHeaders": {
    "Content-Type": "application/pdf"
  }
}

---

Complete Update Upload

POST /knowledge/documents/update/upload-complete

Finalize document update and trigger reprocessing.

Request Body

Field	Type	Required	Description
uploadId	string	Yes	The uploadId from update/upload-link response

Request Example

{
  "uploadId": "upload-uuid"
}

Response

{
  "s3Key": "agents/agent-id/production/kb-abc123/refund-policy-v2.pdf",
  "documentId": "document-uuid",
  "name": "Refund Policy",
  "updatedAt": "2026-01-16T12:00:00.000Z",
  "status": "pending"
}

---

Update Metadata

PATCH /knowledge/documents/metadata

Update document display name and/or metadata without re-uploading the file.

Request Body

Field	Type	Required	Description
agentId	string	Yes	Agent UUID
environment	string	Yes	development, staging, or production
knowledgeBaseId	string	Yes	Knowledge base UUID
s3Key	string	*	Document path. Required if customDocumentId not provided.
customDocumentId	string	*	Your external document ID. Required if s3Key not provided.
name	string	No	New display name
metadata	object	No	New custom metadata (replaces existing)

Request Example

{
  "agentId": "your-agent-id",
  "environment": "production",
  "knowledgeBaseId": "kb-abc123",
  "s3Key": "agents/agent-id/production/kb-abc123/refund-policy.pdf",
  "name": "Refund Policy (Updated)",
  "metadata": {
    "category": "policy",
    "locale": "en",
    "reviewed": "true"
  }
}

Response

{
  "s3Key": "agents/agent-id/production/kb-abc123/refund-policy.pdf",
  "documentId": "document-uuid",
  "name": "Refund Policy (Updated)",
  "metadata": {
    "category": "policy",
    "locale": "en",
    "reviewed": "true"
  },
  "updatedAt": "2026-01-16T14:00:00.000Z"
}

---

Get Document

GET /knowledge/documents

Retrieve metadata for a specific document.

Query Parameters

Parameter	Type	Required	Description
agentId	string	Yes	Agent UUID
environment	string	Yes	development, staging, or production
knowledgeBaseId	string	Yes	Knowledge base UUID
s3Key	string	*	Document path. Required if customDocumentId not provided.
customDocumentId	string	*	Your external document ID. Required if s3Key not provided.

Request Example

GET /knowledge/documents?agentId=your-agent-id&environment=production&knowledgeBaseId=kb-abc123&s3Key=agents/agent-id/production/kb-abc123/refund-policy.pdf

Response

{
  "s3Key": "agents/agent-id/production/kb-abc123/refund-policy.pdf",
  "documentId": "document-uuid",
  "customDocumentId": "DOC-12345",
  "name": "Refund Policy",
  "status": "ready",
  "metadata": {
    "category": "policy",
    "locale": "en"
  },
  "createdAt": "2026-01-15T12:00:00.000Z",
  "updatedAt": "2026-01-16T14:00:00.000Z"
}

Response Fields

Field	Type	Description
s3Key	string	Document path in storage
documentId	string	System-generated document UUID
customDocumentId	string	Your external document ID (if provided during upload)
name	string	Document display name
status	string	Processing status (see Status Values)
metadata	object	Custom key-value pairs
createdAt	string	ISO 8601 creation timestamp
updatedAt	string	ISO 8601 last update timestamp

---

Delete Document

DELETE /knowledge/documents

Remove a document from the knowledge base.

Request Body

Field	Type	Required	Description
agentId	string	Yes	Agent UUID
environment	string	Yes	development, staging, or production
knowledgeBaseId	string	Yes	Knowledge base UUID
s3Key	string	*	Document path. Required if customDocumentId not provided.
customDocumentId	string	*	Your external document ID. Required if s3Key not provided.

Request Example

{
  "agentId": "your-agent-id",
  "environment": "production",
  "knowledgeBaseId": "kb-abc123",
  "customDocumentId": "DOC-12345"
}

Response

{
  "success": true,
  "s3Key": "agents/agent-id/production/kb-abc123/refund-policy.pdf",
  "documentId": "document-uuid"
}