Create URL Document | SpeechifyAI API

curl -X POST https://api.speechify.ai/v1/agents/knowledge-bases/kb_01jqr8x9zg5k2m3n4p5q6r7s8t/documents/url \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "url": "https://example.com/webhook",
  "folder_id": "kfolder_01krdk9hzct70r12s7z5a4xtsh"
}'

{
  "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",
  "source_url": "example",
  "error": "example"
}

Fetch a URL via Firecrawl and ingest the rendered content as a document. The fetch happens synchronously; expect a few seconds per page. Use the sitemap / crawl endpoints for multi-page imports.

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_...).

Headers

Idempotency-KeystringOptional<=255 characters

A client-generated key (an opaque string, max 255 chars) that makes a side-effect POST safe to retry: the server runs the operation exactly once and replays the first response (its status and body) for 24 hours. Reusing a key with a different request body, or while the first request is still in flight, returns 409 idempotency_conflict. A replayed response carries the Idempotent-Replayed: true header.

A client-generated key (an opaque string, max 255 chars) that makes a side-effect POST safe to retry: the server runs the operation exactly once and replays the first response (its status and body) for 24 hours. Reusing a key with a different request body, or while the first request is still in flight, returns `409 idempotency_conflict`. A replayed response carries the `Idempotent-Replayed: true` header.

Request

This endpoint expects an object.

urlstringRequiredformat: "uri"

folder_idstring or nullOptional

Folder to drop the document into. Prefixed wire identifier (kfolder_<26 char Crockford base32>); null/omitted = 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 document was accepted and is being fetched + embedded asynchronously. The returned row is a placeholder with status: fetching; poll the document until it reaches ready or failed.

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

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.

Errors

400

Bad Request Error

401

Unauthorized Error

404

Not Found Error

409

Conflict Error