>unstuck engine

> REST API

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 GET with query params, repeatable params accept ?x=a&x=b and ?x=a,b.
  • Writes are POST with a JSON body; create/update/soft-delete usually share one endpoint, discriminated by id (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) running must carry its type's main input, else signal_config_invalid names the missing details.field; save it as draft to keep an incomplete one. Inbound webhook endpoints on a config are managed with endpoint_op on update-signal-settings, each with its own engagement_points, autoqualify and (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.