API ReferenceHosted APIs

Create Route

Beta
Add a route: a method + path answered by a resolver. `store_query`, `store_document` and `store_aggregate` serve a store; `store_write` lands the POST body as a document (`write_mode` create / replace / merge; POST only, never on a public API, counted against `daily_write_cap`, deduplicated on `Idempotency-Key`); `run_latest` serves the newest structured output of a schedule trigger's runs; `run` starts a run through a webhook trigger per request (POST only, never on a public API) and waits up to `wait_seconds` before answering 202 with a handle to poll at `/_runs/{run_id}`; `file` serves one published file, or a whole published tree when the path ends in `*` (`/app/*` with `file_root` and `file_index`). Where-clause values and the document id may be `{{query.x}}`, `{{path.x}}` or `{{body.x}}` templates bound from the consumer's request, or `{{user.x}}` claims of the verified caller on a `user_token`, `workspace` or `owner` API; a clause whose template is absent is skipped. On those three modes a written document is stamped `user_identity` as the caller and only they can replace or merge it. Two bindings are refused at write time: `{{user.*}}` on an API that names no caller, and a clause on `user_identity` bound from a request template, which would let any caller read any user's rows. 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

api_idstringRequired

Hosted API id (prefixed external id, api_...).

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.
methodenumRequired
pathstringRequired

Lowercase segments of letters, digits, . _ - or a {param}; /openapi.json and /_runs are reserved.

resolverobjectRequired

What answers a route. type selects the fields that apply: store_query (store_id, collection, where, order_by, limit), store_document (store_id, collection, document_id), store_aggregate (store_id, collection, where, group_by, metrics: a summary in one request, from the same implementation as the collection’s aggregate operation), store_write (store_id, collection, write_mode, document_id: the request body lands as a document, the fast path past a run for the one thing a read resolver cannot do; POST only, never on a public API, and on an API that names its caller the document is that person’s), run_latest (trigger_id of a schedule trigger), run (trigger_id of a webhook trigger, wait_seconds), file (file_path of one published file; or, on a route whose path ends in *, file_root and file_index for a whole published tree).

namestringOptional
descriptionstringOptional<=1000 characters
response_schemamap from strings to anyOptional
cache_ttl_secondsintegerOptional0-3600
enabledbooleanOptional
Enabled when omitted.

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

Response

The created route.
idstringformat: "^route_[0-9a-hjkmnp-tv-z]{26}$"
api_idstringformat: "^api_[0-9a-hjkmnp-tv-z]{26}$"
methodenum
pathstring

Lowercase segments, one-segment {params}, and optionally a trailing * that serves a published tree (file routes only).

namestring
descriptionstring
resolverobject

What answers a route. type selects the fields that apply: store_query (store_id, collection, where, order_by, limit), store_document (store_id, collection, document_id), store_aggregate (store_id, collection, where, group_by, metrics: a summary in one request, from the same implementation as the collection’s aggregate operation), store_write (store_id, collection, write_mode, document_id: the request body lands as a document, the fast path past a run for the one thing a read resolver cannot do; POST only, never on a public API, and on an API that names its caller the document is that person’s), run_latest (trigger_id of a schedule trigger), run (trigger_id of a webhook trigger, wait_seconds), file (file_path of one published file; or, on a route whose path ends in *, file_root and file_index for a whole published tree).

cache_ttl_secondsinteger0-3600

Cache-Control max-age on GET responses, and the shared response cache’s lifetime for store and run_latest routes; 0 disables caching, except on a public API, where a GET route with 0 is served with the platform default of 60 seconds so an anonymous crawler never reads storage per request. File routes are never in the response cache; they carry the header for the edge.

enabledboolean
created_atdatetime
updated_atdatetime
response_schemamap from strings to anyOptional
Optional JSON Schema of the response body, rendered into the OpenAPI document.

Errors

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