Update Knowledge Base Document

curl -X PATCH https://api.speechify.ai/v1/agents/knowledge-bases/kb_01jqr8x9zg5k2m3n4p5q6r7s8t/documents/doc_01jqr8x9zg5k2m3n4p5q6r7s8t \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'

{
  "id": "doc_01knthz1d4v2bn8y9wz5ewjagk",
  "kb_id": "kb_01jqr8x9zg5k2m3n4p5q6r7s8t",
  "source_kind": "file",
  "folder_id": "kfolder_01jqr8x9zg5k2m3n4p5q6r7s8t",
  "filename": "example",
  "content_type": "example",
  "byte_size": 1,
  "char_count": 10,
  "chunk_count": 10,
  "status": "fetching",
  "created_at": "2026-06-24T18:03:11Z",
  "updated_at": "2026-06-24T18:03:11Z",
  "content_preview": "example",
  "preview_truncated": true,
  "dependent_agents": [
    {
      "id": "agent_01jqr8x9zg5k2m3n4p5q6r7s8t",
      "name": "Example name"
    }
  ],
  "source_url": "example",
  "error": "example",
  "refresh": {
    "enabled": true,
    "interval_days": 1,
    "auto_remove_enabled": true,
    "last_refreshed_at": "2026-06-24T18:03:11Z",
    "consecutive_fetch_failures": 1
  }
}

Update a document. Currently supports moving the document between folders via folder_id.

Authentication

AuthorizationBearer

Enter your API key with the Bearer prefix, e.g. ‘Bearer sk_…’.

Path parameters

kb_idstringRequired

Knowledge base id (prefixed external id, kb_...).

document_idstringRequired

Knowledge-base document id (prefixed external id, doc_...).

Request

This endpoint expects an object.

folder_idstring or nullOptional

Destination folder. Prefixed wire identifier (kfolder_<26 char Crockford base32>); null moves the document to the knowledge base root.

Response headers

X-Request-IDstring

Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends an X-Request-ID request header the server echoes it back (sanitized and length-capped) so one logical request can be traced end-to-end; otherwise the server generates a fresh value. Log it on every response and quote it in support requests - it is the stable handle that ties your observation to Speechify’s server-side logs, and it matches the request_id field in the error envelope.

Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends an `X-Request-ID` request header the server echoes it back (sanitized and length-capped) so one logical request can be traced end-to-end; otherwise the server generates a fresh value. Log it on every response and quote it in support requests - it is the stable handle that ties your observation to Speechify's server-side logs, and it matches the `request_id` field in the error envelope.

Response

The updated document.

idstringformat: "^doc_[0-9a-hjkmnp-tv-z]{26}$"

kb_idstringformat: "^kb_[0-9a-hjkmnp-tv-z]{26}$"

Prefixed wire identifier (kb_<26 char Crockford base32>) of the knowledge base the document belongs to.

source_kindenum

How the document entered the KB. file is the upload path, text is inline pasted content, url is fetched via Firecrawl. Sitemap and crawl imports also produce url rows.

folder_idstring or nullformat: "^kfolder_[0-9a-hjkmnp-tv-z]{26}$"

Folder this document lives in. Null for root-level (unfiled) documents. Mutated via the move endpoint.

filenamestring

content_typestring

byte_sizelong

char_countinteger

chunk_countinteger

statusenum

Document lifecycle. fetching is the pre-scrape state used only by url-sourced rows; file and text docs skip straight to embedding because their content is available synchronously. Terminal states are ready and failed.

created_atdatetime

updated_atdatetime

content_previewstring

preview_truncatedboolean

dependent_agentslist of objects

source_urlstring

Source URL for url-sourced documents (and the sitemap / crawl imports that produce them). Empty string for file and text rows.

errorstring

Populated when status is failed.

refreshobject

Per-document auto-refresh state. Only populated for url-sourced documents; file and text rows omit this and clients hide auto-refresh affordances accordingly.

Errors

400

Bad Request Error

401

Unauthorized Error

404

Not Found Error