Every operation the app, the CLI and the MCP tools perform is an HTTPS
endpoint you can call directly. The machine-readable contract is
openapi.json (OpenAPI 3.1, generated from the same source
as the tools — import it into Postman, Bruno, or a code generator).
Base URL and auth
https://<api-url>/functions/v1/<endpoint>
Authorization: Bearer unstk_… # an API key (Settings → API keys)
<api-url> is printed in the app next to your keys and is the servers[0].url
of openapi.json. Signed-in sessions (JWT) are accepted on the same endpoints;
keys are the door for integrations.
One response shape
// success
{ "result": "ok", "data": <object|array|null>, "error": null, "message": null, "details": null, "meta": <object|null> }
// error
{ "result": "error", "data": null, "error": "<code>", "message": "<one sentence>", "details": <object|null>, "meta": null }
Branch on result. error is a stable machine-readable code (plan_upgrade_required,
duplicate_config, rate_limit_exceeded, …) and details carries the
structured extras (the existing id, the allowed values, the limit). meta
holds paging (total, page, pages_total) and operation hints
(meta.operation). Every response carries X-Request-Id; quote it to support.
Conventions
- Reads are
GETwith query params, repeatable params accept?x=a&x=band?x=a,b. - Writes are
POSTwith a JSON body; create/update/soft-delete usually share one endpoint, discriminated byid(update) vs the create key (signal_type_code,code,audience_id+connection_id). - Codes, never internal ids, address catalog entities (
signal_type_code,connector_type_code,plan_code); your own rows are addressed by their UUID. - Nothing is hard-deleted:
status: "deleted_by_user"soft-deletes. - Configs are stored verbatim — send the complete merged object on update.
- A running signal config is checked: one saved as (or left)
runningmust carry its type's main input, elsesignal_config_invalidnames the missingdetails.field; save it asdraftto keep an incomplete one. Inbound webhook endpoints on a config are managed withendpoint_oponupdate-signal-settings, each with its ownengagement_points,autoqualifyand (webhook endpoints only)party. - Audiences need a name. A deleted signal config's id stays in an audience's filters,
and its past signals still count, until you remove it or set
ignore_deleted_rules. - Projects: billing belongs to the project's paying workspace. Any other workspace of
the project sees its plan and its own usage only, and a billing write from it answers
billing_delegated. - Rate limits are per workspace and per plan: rate-limits.md.
First call
curl -s -H "Authorization: Bearer unstk_…" "https://<api-url>/functions/v1/whoami" | jq .
curl -s -H "Authorization: Bearer unstk_…" "https://<api-url>/functions/v1/list-leads?stage=qualified&page_size=5" | jq '.meta, .data[0]'
Per-endpoint contracts (parameters, meta, every error code) live in
docs/api/ — only the endpoints tagged auth: jwt+api_key or
public are customer-facing; openapi.json contains exactly those.