Reference

API reference

Plain JSON over HTTPS, Bearer-token auth, OpenAPI 3.1 spec. Nearly everything the dashboard does, you can do over the API — and the spec describes all of it.

Authentication

Generate a token from Settings → API tokens → New token. The plaintext is shown once at creation; only the SHA-256 hash is stored on our side. Send it as a Bearer header on every request:

Authorization: Bearer coag_<id>_<secret>

Tokens are scoped to your workspace and inherit the owner's permissions. Rotate from the same screen at any time — the new token is recognised on the next request, no API restart needed.

Base URL

Production    https://api.coagentic.work
Local dev     http://localhost:4000

Every JSON endpoint accepts and returns application/json. 4xx responses include a { error: string } body; 5xx returns a generic message and a request id you can quote on a support email.

Common calls

curl -H 'Authorization: Bearer coag_xxx_xxx' \
     https://api.coagentic.work/projects

curl -X POST https://api.coagentic.work/projects \
     -H 'Authorization: Bearer coag_xxx_xxx' \
     -H 'Content-Type: application/json' \
     -d '{ "name": "My site", "type": "landing" }'

curl -X POST 'https://api.coagentic.work/rows?tableId=tbl_…' \
     -H 'Authorization: Bearer coag_xxx_xxx' \
     -H 'Content-Type: application/json' \
     -d '{ "data": { "email": "[email protected]" } }'

# :workflowId is shown in the workflow editor.
# If the workflow has a secret, sign the raw body and send the
# hex digest in the X-Coagentic-Signature header.
curl -X POST 'https://api.coagentic.work/webhooks/wf_…' \
     -H 'X-Coagentic-Signature: <hmac-sha256-hex>' \
     -H 'Content-Type: application/json' \
     -d '{ "order_id": 42, "amount_cents": 4900 }'

Endpoint groups

Outbound webhooks

The other direction: Coagentic POSTs to your endpoint when something happens in your workspace. Add one under Settings → Outbound webhooks, choose the events, and keep the signing secret it gives you.

Verifying a delivery. Every request carries three headers: X-Coagentic-Timestamp (unix seconds), X-Coagentic-Signature-V2 — HMAC-SHA256 of `${timestamp}.${rawBody}` with your signing secret — and X-Coagentic-Signature, the older form over the body alone. Prefer V2 and reject timestamps outside a few minutes; that is what makes a captured request useless later. Compare with a constant-time equality check.

Retries. Anything other than a 2xx — including a timeout past 10 seconds — is retried up to five times with exponential backoff starting at 5 seconds. Redirects are not followed. Endpoints on private or link-local addresses are refused outright, so a webhook cannot be pointed at our own internals.

Make it idempotent. A retry can deliver the same event twice, and a delivery that timed out may already have been processed. Key on the event's own id.

Full spec

The complete machine-readable reference is at /openapi.json (OpenAPI 3.1) — every group on this page, thirty-two paths. Pipe it into openapi-typescript for a typed TS client, or load it in any Postman / Insomnia / Bruno workspace.

Swagger UI lives at /docs on the API host — interactive reference with try-it-now buttons once you paste a Bearer token.