API ReferenceStores

Create Document

Beta
Write a document, minting an id when none is given. Prefer `putDocument` with a stable id you derive from the content, so a retry never duplicates. Bounded by the store's document limit (409 `store_document_limit_reached`). `query` and `batch` are reserved ids (400 `validation_failed`). Dark launch: requires the `hosted_apis_access` entitlement (402 `hosted_apis_not_in_plan` otherwise).

Authentication

AuthorizationBearer

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

Path parameters

store_idstringRequired

Store id (prefixed external id, store_...).

collectionstringRequired

Collection name (lowercase letters, digits, _, -).

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.
datamap from strings to anyRequired

The document body (a JSON object, at most 256 KiB). On updateDocument, the fields to merge; a null removes a field.

idstringOptional

On createDocument, the id to write at (letters, digits, _ . - : ~ @ +, at most 200, not the reserved query or batch); minted when absent. Ignored on putDocument / updateDocument, where the URL names it.

Response headers

Speechify-Request-IdstringOptional
Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends a `Speechify-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. The legacy alias `X-Request-ID` carries the same value and is still accepted on requests, until 2027-07-24. Prefer the un-prefixed name (RFC 6648).
ETagstringOptional

The document’s current revision as a strong entity tag. Send it back in If-Match to write only if nobody else has written since - the same value is on the body as revision.

Response

The written document.
idstring
collectionstring
versioninteger>=1

Incremented on every write to this id. It counts writes to a live document and starts again at 1 if the id is deleted and written again, so use revision, not this, to write conditionally.

revisionstringformat: "^[0-9a-f]{32}$"

Names this exact version of the document and never repeats - not for a later write, and not for a document deleted and written again at the same id. Send it in If-Match (quoted, as the ETag of a read returns it) to write only if nothing has changed since.

size_bytesinteger>=0
created_atdatetime
updated_atdatetime
sourceobjectOptional

The durable run (and its journal step) that wrote this version. Absent for a direct API write.

datamap from strings to anyOptional
The document body. Absent when the caller asked for index rows only.

Errors

400
Bad Request Error
401
Unauthorized Error
402
Payment Required Error
404
Not Found Error
409
Conflict Error
503
Service Unavailable Error