Create Hosted API | SpeechifyAI API

Create a hosted API. The slug is a DNS label, globally unique on the shared domain (409 hosted_api_slug_taken) and immutable afterwards. auth_mode names the audience, narrowest first: owner, workspace (the platform’s own credentials), user_token (a JWT your backend signs per user), consumer_key (a ck_ key you mint) or public (anyone, reads only). A workspace can refuse public as policy (403 hosted_api_public_refused). Reads, runs and writes are each bounded per UTC day (daily_read_cap, daily_run_cap, daily_write_cap). Dark launch: requires the hosted_apis_access entitlement (402 hosted_apis_not_in_plan otherwise).

Create a hosted API. The slug is a DNS label, globally unique on the shared domain (409 `hosted_api_slug_taken`) and immutable afterwards. `auth_mode` names the audience, narrowest first: `owner`, `workspace` (the platform's own credentials), `user_token` (a JWT your backend signs per user), `consumer_key` (a `ck_` key you mint) or `public` (anyone, reads only). A workspace can refuse `public` as policy (403 `hosted_api_public_refused`). Reads, runs and writes are each bounded per UTC day (`daily_read_cap`, `daily_run_cap`, `daily_write_cap`). 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_…’.

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.

slugstringRequiredformat: "^[a-z0-9](?:[a-z0-9-]{1,38}[a-z0-9])?$"

3-40 lowercase letters, digits or hyphens; a DNS label, unique on the shared domain; immutable.

namestringRequired

descriptionstringOptional<=1000 characters

auth_modeenumOptional

consumer_key when omitted. public is refused with 403 hosted_api_public_refused where the workspace’s policy does not allow internet-facing APIs.

cors_originslist of stringsOptional

daily_run_capintegerOptional1-100000

Runs the API may start per UTC day through its run routes; 1000 when omitted.

daily_read_capintegerOptional1-10000000

Reads the API may serve from storage per UTC day; 100000 when omitted.

daily_write_capintegerOptional1-1000000

Documents the API’s write routes may land per UTC day; 10000 when omitted.

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

user_token_jwks_urlstringOptional<=500 characters

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

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

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

slugstring

hostnamestring

The public host, <slug>.<hosted-api domain>; empty where no domain is configured.

base_urlstring

namestring

descriptionstring

auth_modeenum

Who the API answers, narrowest first. owner: only the API’s owner, with their own Speechify API key or console session. workspace: any member of the owning workspace, the same way. user_token: every request presents a short-lived JWT your backend signed for the calling user (sub, exp within 24 hours, optional aud naming this API), verified against the API’s signing secret (HS256) or its registered JWKS URL (RS256 / ES256 / EdDSA). consumer_key: every request presents a ck_ bearer minted for this API. public: no credential; only read resolvers may be served, the per-IP limiter is the only bound, and a workspace can refuse it as policy (hosted_apis_public_allowed). The three modes that name a person (owner, workspace, user_token) let routes bind {{user.sub}}, key the response cache per person, and stamp a written document as that person’s.

cors_originslist of strings

Browser origins allowed to call the API (* for any). Empty for server-to-server only.

enabledboolean

daily_run_capinteger1-100000

Runs the API’s run routes may start per UTC day; the spend ceiling behind a leaked consumer key.

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

user_token_jwks_urlstring or null

The key set end-user tokens are verified against when set (an https URL on a public host, read on demand and cached briefly). When null, tokens are verified against the API’s signing secret.

user_token_secret_hintstring or null

The masked signing secret end-user tokens are verified against (the rotate-user-token-secret verb mints it); null until minted.

created_atdatetime

updated_atdatetime

daily_read_capintegerOptional1-10000000

Reads the API’s store, file and run_latest routes may serve from storage per UTC day; the storage ceiling behind a hot path. Always present on a current API; optional on the wire so a reader built before it existed keeps parsing. A response served from the cache is not a read. Past the cap a read route answers 429 route_read_limit_reached. Without Redis nothing counts: a public route is paused by the limiter in that state, a keyed or tokened caller passes.

daily_write_capintegerOptional1-1000000

Documents the API’s write routes may land per UTC day; the storage ceiling behind a leaked key on a write route. Past the cap a write route answers 429 route_write_limit_reached. Optional on the wire for the same reason as daily_read_cap.

Errors

400

Bad Request Error

401

Unauthorized Error

402

Payment Required Error

404

Not Found Error

409

Conflict Error

$	curl -X POST https://api.speechify.ai/v1/apis \
>	-H "Authorization: Bearer <token>" \
>	-H "Content-Type: application/json" \
>	-d '{
>	"slug": "acme-news",
>	"name": "Acme News"
>	}'

1	{
2	"id": "api_01jqr8x9zg5k2m3n4p5q6r7s8t",
3	"slug": "acme-news",
4	"hostname": "acme-news.apis.speechify.ai",
5	"base_url": "https://acme-news.apis.speechify.ai",
6	"name": "string",
7	"description": "string",
8	"auth_mode": "consumer_key",
9	"cors_origins": [
10	"string"
11	],
12	"enabled": true,
13	"daily_run_cap": 1,
14	"project_id": "string",
15	"user_token_jwks_url": "string",
16	"user_token_secret_hint": "uts_••••wxyz",
17	"created_at": "2024-01-15T09:30:00Z",
18	"updated_at": "2024-01-15T09:30:00Z",
19	"daily_read_cap": 1,
20	"daily_write_cap": 1
21	}