API ReferenceKnowledge BasesDocument sources

Create Multi-URL Import

Beta

Kick off an async multi-URL import. Accepts 1..N URLs in a single job (capped per-deployment, default 50) and runs the same per-URL pipeline as the sitemap importer. Returns 202 with the import job row; client polls GET /{kb_id}/imports for progress.

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

Speechify-VersionstringOptional
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.

Request

This endpoint expects an object.
urlslist of stringsRequired
folder_idstring or nullOptional

Folder to import the documents 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.

Response

Import job queued.
idstringformat: "^import_[0-9a-hjkmnp-tv-z]{26}$"
kb_idstringformat: "^kb_[0-9a-hjkmnp-tv-z]{26}$"
kindenum
statusenum

The one lifecycle vocabulary shared by every async job (batch calls, knowledge-base imports, agent-test runs, suite runs): pending → running → a terminal state.

  • pending - accepted but not yet executing (queued for a worker, or deferred to a future scheduled time).
  • running - actively executing.
  • completed - ran to conclusion. The single terminal-success verb. For a job that produces a pass/fail judgment (an agent-test run), this means it produced a verdict - read the separate verdict field for the judgment, not this status.
  • failed - could not complete (an infrastructure or input failure), distinct from a completed job whose verdict is failed.
  • cancelled - cancelled before reaching a natural terminal state.
totalinteger

Total URLs to process (the progress denominator).

completedinteger
URLs imported successfully.
failedinteger
URLs that failed to import.
paramsmap from strings to any

JSON blob whose shape depends on kind — typically url, max_pages, max_depth. Read it for display only.

created_atdatetime
updated_atdatetime
started_atdatetime or null
ended_atdatetime or null
errorstring

Errors

400
Bad Request Error
401
Unauthorized Error
404
Not Found Error
409
Conflict Error