Upload a document

POST

/v1/knowledge-bases/{kb_id}/documents

• API base path

Upload a file to a knowledge base. The document is processed asynchronously through the ingestion pipeline: parse, chunk, embed, index.

Returns immediately with a 202 Accepted response containing the document record in pending status. Poll the document detail endpoint or register a webhook to be notified when processing completes.

Supported file types:

• Tier 1 (parsed via external service): PDF, DOCX, PPTX, XLSX, PNG, JPG, JPEG, WEBP, TIFF
• Tier 2 (direct ingestion, no parsing cost): TXT, MD, HTML, HTM, CSV, TSV, JSON

Limits: Max file size 50 MB.

Authorizations

• BearerApiKey

Parameters

Path Parameters

kb_id

required

string

/^kb_/

Example

kb_a1b2c3d4e5

Knowledge base ID

Request Body ^required

object

file

required

The file to upload. Max 50 MB. Allowed extensions: pdf, docx, pptx, xlsx, png, jpg, jpeg, webp, tiff, txt, md, html, htm, csv, tsv, json.

string format: binary

metadata

Optional JSON string of arbitrary metadata to attach to the document. This metadata is filterable at search time.

string

Example

{"department": "engineering", "version": 2}

Responses

202

Document accepted for processing

object

data

required

object

id

required

Document ID (prefixed with doc_)

string

Example

doc_f6g7h8i9j0

kb_id

required

Parent knowledge base ID

string

Example

kb_a1b2c3d4e5

account_id

required

Owning account ID

string

Example

acc_x9y8z7w6v5

name

required

Original file name

string

Example

product-guide.pdf

file_type

required

File extension

string

Example

pdf

file_size_bytes

File size in bytes

integer

nullable

Example

2048576

page_count

Number of pages (for Tier 1 files, set after parsing)

integer

nullable

Example

15

chunk_count

required

Number of chunks generated from this document

integer

Example

34

status

required

string

Allowed values: pending parsing chunking embedding ready failed

error_detail

Error message if status is failed

string

nullable

metadata

required

User-supplied metadata (filterable at search time)

object

key

additional properties

any

Example

{
  "department": "engineering",
  "version": 2
}

storage_path

Internal storage path

string

nullable

Example

acc_x9y8z7w6v5/kb_a1b2c3d4e5/doc_f6g7h8i9j0/product-guide.pdf

created_at

required

string format: date-time

Example

2026-02-10T12:00:00.000Z

updated_at

required

string format: date-time

Example

2026-02-10T12:01:30.000Z

400

Request validation failed

object

error

required

object

code

required

Machine-readable error code

string

Allowed values: VALIDATION_ERROR AUTHENTICATION_ERROR NOT_FOUND CONFLICT RATE_LIMIT_EXCEEDED USAGE_LIMIT_EXCEEDED EXTERNAL_SERVICE_ERROR INTERNAL_ERROR

Example

VALIDATION_ERROR

message

required

Human-readable error message

string

Example

Invalid request body

details

Additional error details (e.g., validation issues)

object

key

additional properties

any

Example

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body",
    "details": {
      "issues": [
        {
          "path": [
            "name"
          ],
          "message": "Required"
        }
      ]
    }
  }
}

401

Authentication failed or missing

object

error

required

object

code

required

Machine-readable error code

string

Allowed values: VALIDATION_ERROR AUTHENTICATION_ERROR NOT_FOUND CONFLICT RATE_LIMIT_EXCEEDED USAGE_LIMIT_EXCEEDED EXTERNAL_SERVICE_ERROR INTERNAL_ERROR

Example

VALIDATION_ERROR

message

required

Human-readable error message

string

Example

Invalid request body

details

Additional error details (e.g., validation issues)

object

key

additional properties

any

Example

{
  "error": {
    "code": "AUTHENTICATION_ERROR",
    "message": "Invalid or missing API key"
  }
}

404

Resource not found

object

error

required

object

code

required

Machine-readable error code

string

Allowed values: VALIDATION_ERROR AUTHENTICATION_ERROR NOT_FOUND CONFLICT RATE_LIMIT_EXCEEDED USAGE_LIMIT_EXCEEDED EXTERNAL_SERVICE_ERROR INTERNAL_ERROR

Example

VALIDATION_ERROR

message

required

Human-readable error message

string

Example

Invalid request body

details

Additional error details (e.g., validation issues)

object

key

additional properties

any

Example

{
  "error": {
    "code": "NOT_FOUND",
    "message": "KnowledgeBase not found: kb_nonexistent"
  }
}

429

Rate limit or usage limit exceeded

object

error

required

object

code

required

Machine-readable error code

string

Allowed values: VALIDATION_ERROR AUTHENTICATION_ERROR NOT_FOUND CONFLICT RATE_LIMIT_EXCEEDED USAGE_LIMIT_EXCEEDED EXTERNAL_SERVICE_ERROR INTERNAL_ERROR

Example

VALIDATION_ERROR

message

required

Human-readable error message

string

Example

Invalid request body

details

Additional error details (e.g., validation issues)

object

key

additional properties

any

Examples

Rate limit exceeded

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded"
  }
}

Page usage limit exceeded

{
  "error": {
    "code": "USAGE_LIMIT_EXCEEDED",
    "message": "Usage limit exceeded for pages_processed. Upgrade your plan or wait for the next billing period.",
    "details": {
      "limit": 1000,
      "current_usage": 998,
      "plan": "starter",
      "requested": 5
    }
  }
}