API reference
Help centerGet an API key
API reference

Robofono API

Endpoints, parameters, code samples in 15 languages, and a console that runs them.

The Robofono API is a plain JSON API over HTTPS for what the app does: reading your locations, usage, calls and events, managing outbound webhooks, and provisioning the clients you sell to. Every path hangs off one base URL at https://api.robofono.com, with a bearer key in a header, snake_case fields, ISO 8601 timestamps in UTC, and the same error shape everywhere.

Base URL
https://api.robofono.com
A single API key does everything. You mint it on the Developers screen in your settings and tick the scopes it carries, and from then on what it reaches follows from your account and those scopes and nothing else.

Quick start

  1. 1

    Get your API key

    Open Robofono and go to Settings, then Developers. Mint a key, tick the scopes this integration needs, and copy the value straight into your secret store.

    The key is shown once and never again, because only its hash is stored. If you lose it, revoke it and mint another.

  2. 2

    Find your location ids

    Most calls need none. A location is a workspace_id in the API: a key bound to 1 location already answers for it.

    GET /v1/locations lists the locations your key covers, each with the id the other endpoints take.

  3. 3

    Make your first request

    Ask for the first 5 locations the key covers:

    curl "https://api.robofono.com/v1/locations?limit=5" \
      -H "Authorization: Bearer ck_live_EXAMPLEKEY00000000000000000000000000000"

    The answer is a page of data and a cursor to walk it with:

    {
      "data": [
        {
          "id": "ws_4q8n1v6z0c3r7t2y5u9i",
          "name": "Northbound Coffee, Main Street",
          "status": "active",
          "created_at": "2026-06-02T08:41:00.000Z"
        }
      ],
      "has_more": true,
      "next_cursor": "MjAyNi0wNi0wMlQwODo0MTowMC4wMDBafHdzXzE"
    }

    A 401 here means the header did not arrive as the server expected it. A 403 means the key is real but is missing usage:read.

Concepts

How keys, limits, paging, retries and errors work, once, for every endpoint below.


Authentication #

Send your key as a bearer token, and know what a missing or too-narrow key answers.

Every call carries your key in an Authorization header:

Authorization: Bearer ck_live_EXAMPLEKEY00000000000000000000000000000

An X-API-Key header holding the bare key does the same job, and either form works. Use whichever your HTTP client makes easy.

The base URL for every path in this reference is https://api.robofono.com, so a first call looks like this:

curl "https://api.robofono.com/v1/locations?limit=5" \
  -H "Authorization: Bearer ck_live_EXAMPLEKEY00000000000000000000000000000"

A key is a credential, not a public token. It grants everything its scopes allow, on every workspace it reaches, with no second factor and no confirmation step. Keep it on a server you control, in an environment variable or a secret store, and never ship it in client-side code, a mobile app, or anything a browser downloads.

A key is 32 random bytes behind a cosmetic prefix, and only its hash is stored. The full value therefore exists in exactly 1 response body, once: copy it when it is shown, because Robofono cannot show it again. No key call ever answers a cookie, and a key never reaches the screens a person signs in to.

A call with no key, or with a key that is unknown, revoked or expired, answers 401:

{
  "error": {
    "code": "unauthorized",
    "message": "This endpoint needs an API key."
  }
}

A key that is real but does not reach this far answers 403, and the message says which limit it ran into:

{
  "error": {
    "code": "forbidden",
    "message": "This key needs one of: webhooks:write."
  }
}

What your key reaches #

Your account decides how far a key reaches, and its scopes decide what it may do there.

There is 1 API key, and 2 things decide what you can do with it.

  • Your account. A key is minted on an account and reaches exactly as far as that account does. A key on a single location reaches that location. A key on an agency account also reaches the client locations on its book, which is what the Clients group is for. A key on the platform's own account reaches everything. You do not choose this and there is nothing to switch on: it already follows from who you are.
  • The scopes you gave it. On the Developers screen you tick exactly what this key may do: read locations, usage and events, read calls, manage outbound webhooks, read or write clients, allocate credits.

Give a key only the scopes its job needs, and mint a separate key for a separate job rather than widening the first one. Revoking a narrow key costs you 1 integration. Revoking a wide one costs you all of them.

Beside the scopes you can pin a key to particular locations, give it an expiry date, and cap how many billable actions it may take in a month. A spent cap answers 429 key_cap_reached and clears with the billing cycle.

Reaching past any of these is 1 answer and never a surprise: 403 with the code forbidden, and a message naming which limit it was. There are 3 of them:

  • This key needs one of: webhooks:write. A missing scope, naming every scope that would have done.
  • That location is not in this key's allowlist. A location the key is not pinned to.
  • That account is not yours. An account this key's own account does not reach.

Nothing else changes across any of them: the same key, the same header, the same base URL.

Rate limits #

Every key gets a per-minute budget, counted separately for reads and for writes.

Requests are counted per key in fixed windows of 60 seconds, with reads and writes counted separately. A write is also a read, so it counts against both, and the tighter of the 2 is what a refusal tells you about.

PlanReads a minuteWrites a minute
Every other plan60060
Agency1,200120
Whitelabel3,000300

The numbers come off the plan of the key's owner rather than off the key itself, because what an integration may spend is a property of what its owner bought. A whitelabel partner's workspace key gets the whitelabel row.

Every successful answer carries x-ratelimit-limit, x-ratelimit-remaining and x-ratelimit-reset. A refusal carries a Retry-After header in seconds beside this body:

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Try again in 34 seconds.",
    "retry_after": 34
  }
}

Back off on the header rather than on a guess. A retry that ignores it spends the next window on the same refusal:

async function call(url, init, attempt = 0) {
  const res = await fetch(url, init);
  if (res.status !== 429 || attempt >= 5) return res;
  const wait = Number(res.headers.get("retry-after") ?? 1);
  await new Promise((done) => setTimeout(done, wait * 1000));
  return call(url, init, attempt + 1);
}

The budget covers the automation endpoints, the Clients endpoints, the assistant endpoint, and the provisioning endpoints, which are metered at the platform tier. An assistant message costs 1 read whatever it goes on to do, and the write it dispatches is counted once, where the write is.

Pagination #

Lists walk by keyset cursor, newest first, so a page cannot skip or repeat a row.

Every list is a keyset walk on (created_time, id) or (created_at, id), newest first. That is what stops a page skipping or repeating a row when new rows land mid-walk, which an offset cannot do. 2 query parameters drive it:

  • limit, between 1 and 200, defaulting to 50.
  • cursor, the opaque value the previous page handed back.

Every list answers the same envelope:

{
  "data": [ ... ],
  "has_more": true,
  "next_cursor": "MjAyNi0wOS0xMlQwOTo0MToxOC4wMDBafGNtdF8x"
}

Walk it by passing next_cursor back as cursor until has_more is false and next_cursor is null:

let cursor = null;
do {
  const url = new URL("https://api.robofono.com/v1/events");
  url.searchParams.set("limit", "100");
  if (cursor) url.searchParams.set("cursor", cursor);
  const page = await (await fetch(url, { headers })).json();
  handle(page.data);
  cursor = page.next_cursor;
} while (cursor);

A cursor is a base64url pair of the sort key and the id. Do not build one by hand, and do not carry one across a change of filters: the walk it describes no longer exists, and the answer is 400 bad_request.

Idempotency #

Every mutation carries an Idempotency-Key, so a retry cannot act twice.

Every mutation on the automation and Clients endpoints carries an Idempotency-Key header, and it is required: without one the call is refused with 400 idempotency_key_required before the handler runs.

Idempotency-Key: a2f1c9d4-8b76-4e05-9a31-77c0e4d21b8f

Anything from 8 to 128 URL-safe characters works, and a UUID is the obvious choice. The first call to arrive with a given key stores its exact response bytes, and a replay inside the next 24 hours reads those bytes back with an Idempotent-Replay: true header, without reaching the handler at all.

That is what makes "no second reply sent, nothing charged twice" structural rather than a promise. A replay never runs the handler, so there is nothing left to charge for.

  • A key is scoped to 1 call: the method, the path and the body it first carried. Reuse it on a different endpoint, or with a different body, and the answer is 409 conflict, because replaying the first call's response would be the API doing 1 thing and reporting another.
  • A second call while the first is still in flight is refused with 409 conflict as well, so 2 racing retries cannot both proceed.
  • A failure is not remembered. If the handler threw, or answered 5xx, the claim is released so the same key can be retried once the cause is fixed. A considered 4xx is stored and replayed.

Generate a fresh key per logical operation and endpoint, and reuse it for every retry of that call. A new key per attempt protects nothing, and 1 key for a whole script run buys a 409 on the next endpoint it touches.

The provisioning endpoints are the exception: there the header is optional. Send one and it is honoured in full, with the same replay, the same 24-hour window and the same 409 conflict on a different body; send none and the call is never refused for it. The provisioning hook has a second guard of its own, a single claim per event per external_id, which is why a redelivery there is answered as a duplicate rather than provisioning again.

Errors #

Every refusal has the same shape, and code is the half your integration switches on.

Every refusal in this API has 1 shape:

{
  "error": {
    "code": "validation_failed",
    "message": "message is required."
  }
}

code is the stable half and is what you switch on. message is for a person reading a log and may be reworded at any time, so never match on it. Some refusals carry an extra member the caller is meant to act on: retry_after, credits_remaining, allocated and used, monthly_action_cap.

Every code the public endpoints send:

CodeStatusWhat happened
unauthorized401No key, or an unknown, revoked or expired one.
forbidden403The key is real and may not do this: a missing scope, a location outside its allowlist, or a platform-only endpoint.
plan_required403The plan does not include this feature.
not_found404No such row, and also the answer for somebody else's row, so no refusal confirms a guessed id.
bad_request400A malformed cursor, an unknown tab, or a method the endpoint does not take.
validation_failed422A field value the handler will not take.
idempotency_key_required400A mutation arrived without the header.
reason_required400A credit grant arrived with no reason on it.
conflict409An idempotency key reused with a different body or still in flight.
credits_depleted409The account's credit pool is empty. Reads keep working.
allocation_depleted409The client's whole allocation for this cycle is spent.
allocation_unset409The client has no allocation yet, so none of their locations may spend.
processing_paused409The phone agent is paused on this account or by its plan.
capability_unsupported409The platform does not offer that action, and never a silent no-op.
pool_insufficient409The credit pool cannot back the allocation asked for.
rate_limited429This key's per-minute window is spent.
key_cap_reached429This key's monthly action cap is spent.
internal500Ours. Retry with the same idempotency key.

Retry rate_limited and internal, honouring Retry-After where it is sent. The 409s are decisions rather than weather: retrying one without changing anything gets the same answer.

The assistant endpoint is the 1 place this shape is not used. It speaks JSON-RPC, so its refusals arrive as JSON-RPC errors.

Credits #

An action through the API costs what the same action costs in the app, and reads cost nothing.

An action taken through this API costs exactly what the same action costs inside the app, and nothing extra. There is no API surcharge and no second meter: an action your integration takes and the same action somebody takes by clicking in Robofono draw on the same balance, at the same rate.

Reads cost nothing at all, and they stay free on an expired plan and an empty wallet. Listing locations, reading usage, calls or events: none of it touches the balance.

The rate depends on what the action is, and the rate for each is the one on your billing screen, which is the single place those numbers are published. The endpoints that charge answer with credits_burned beside the data, read off the ledger row rather than off anything written here, so what you read always agrees with what you were charged.

The charge lands after the action succeeded. A refusal from the platform, a network failure, and an idempotent replay all cost nothing.

What never charges: reading locations, usage, calls or events, and managing outbound webhooks.

3 separate things can pause actions, and each says so with its own code:

  • credits_depleted: the account's credit pool is empty, and a credit pack is the way out.
  • allocation_depleted: the client's credit pool for this cycle is spent, and every location of that client draws on it. Under an agency this is reached long before the account's pool is, and it needs a bigger allocation rather than a pack.
  • key_cap_reached: the monthly action cap set on this key is spent.

GET /v1/usage is where an integration reads all of it: the cycle, what has been spent, what is left, and the same figures per location.

Outbound webhooks #

Subscribe an https endpoint and each event is posted to it, signed, with a retry ladder.

Subscribe an https endpoint with POST /v1/webhooks and Robofono posts each event to it as it happens. Every delivery has the same body:

{
  "id": "whd_3r7t2y5u9i4q8n1v6z0c",
  "type": "location.created",
  "created_at": "2026-09-14T10:04:22.000Z",
  "workspace_id": "ws_4q8n1v6z0c3r7t2y5u9i",
  "data": { ... }
}

and these headers:

  • x-signature-256: sha256= followed by the hex HMAC-SHA256 of the raw body under your signing secret.
  • x-signature-256-previous: the same body signed with the secret you just rotated away. Sent for 24 hours after a rotation and then not at all, so a receiver that has not deployed the new secret keeps working and can watch the window close.
  • x-timestamp: when this attempt was made.
  • x-delivery-id: the attempt's own id, stable across retries of the same delivery.
  • x-event-type: the same value as type in the body, for routing before you parse.

Verify before you trust, over the raw bytes you received. Re-serializing the JSON changes key order and spacing, and every check after that fails in a way that looks exactly like a wrong secret.

import crypto from "node:crypto";

function verify(rawBody, header, secret) {
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(rawBody, "utf8")
    .digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(header ?? "");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Retries. A delivery that does not get a 2xx is retried after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours, then hourly, and is given up 24 hours after it was queued. Answer 2xx as soon as you have stored the event and do your work afterwards: a slow receiver is a retried receiver.

Once per event. An event keeps its id on every retry and is raised once per version of what it describes, so a stored id makes a duplicate free to ignore.

The events. Subscribe to any of location.created, location.deleted, credits.low, credits.depleted, the 6 client.* lifecycle events and the 4 call.* events, or send ["*"] for all of them. An endpoint scoped to some locations hears only about those, and its credits.* events carry no account figures. A Slack destination, set up in your settings, may also take digest.daily, a once-a-day summary.

Call events fire once a call has ended (there is no call.started), in no set order: call.completed or call.failed, 1 call.message_taken per message and 1 call.booking_created per booking. They carry caller details, so protect your endpoint, and never credits.

location.created/deleted  location_id, name
credits.low/depleted      account_id, workspace_id, allowance, burned, remaining, pct,
                          cycle_start, cycle_end (scoped endpoint: workspace_id, event)
client.*                  the client and its workspace
call.completed/failed     call_id, location_id, agent_id, number_id, direction, from, to,
                          caller_name, started_at, ended_at, duration_seconds,
                          billed_seconds, outcome, summary, language, extracted, flagged
call.message_taken        call_id, workspace_id, message: { id, call_id, workspace_id,
                          caller_name, caller_number, body, urgency, status,
                          created_at, updated_at }
call.booking_created      call_id, workspace_id, booking: { id, starts_at, ends_at,
                          time_zone, status, calendar_sync, assignee_name,
                          caller_name, caller_number, caller_email, notes }

Assistants and MCP #

A Model Context Protocol server over this same API, so an assistant can call it as tools.

POST https://api.robofono.com/mcp is a Model Context Protocol server over this same API, so an assistant such as a chat client or an editor can call it as a set of tools. Point your client at that URL with your API key as the bearer token and nothing else is needed: it is stateless, so there is no session to open, no stream to keep and no second credential anywhere.

The plan feature mcp gates the endpoint as a whole. Every tool dispatches to one of the REST paths in this reference using your own key, so the scopes on that key mean here exactly what they mean there, a location outside its allowlist is refused the same way, and an action is metered once rather than twice.

The tools, which appear only when your account and your key's scopes reach them:

  • Context: locations_list, usage_get.
  • Calls, with the calls:read scope: calls_list, calls_get. Durations are in minutes, and neither tool shows credits or recordings.
  • Clients, on an agency account: clients_list, clients_get, clients_usage, clients_allocate_credits, clients_provision.

3 answers are HTTP rather than JSON-RPC, on purpose: 401 with a WWW-Authenticate: Bearer challenge when there is no key, 403 when the plan does not include this, and 405 on GET and DELETE, which a stateless server has nothing to do with.

A rate limit goes the other way and comes back as a JSON-RPC error carrying retry_after, because the client is mid-conversation and needs to match the refusal to the message it sent.

Locations

The locations a key covers. A free read.


Locations #

A location is what the app's location switcher lists. Its id is the workspace_id every endpoint takes.

GET

List locations

GET /v1/locations

List the locations this key covers. A key pinned to some locations lists those and nothing else.

Workspace keyusage:readread
NameInTypeDescription
account_idquerystring
optional
Platform keys only: the account whose locations to list. A customer key reads its own account and may omit it. acc_7t2y5u9i4q8n1v6z0c3r
cursorquerystring
optional
The next_cursor from the previous page. The list is oldest first on (created_at, id). MjAyNi0wNi0wMlQwODo0NTowMC4wMDBafGNoXzE
limitqueryinteger
optional
Page size, 1 to 200. Defaults to 50. 50
Response fields
dataarray
data[].idstring
data[].namestring
data[].statusstring
data[].created_atstring
has_moreboolean
next_cursornull

Failure modes and quotas: Errors · Rate limits

Usage

What this key's account has spent, and the trail of everything that happened. Both are free reads.


Usage #

Credits granted, burned and left.

GET

Read usage

GET /v1/usage

Read credits granted, burned and left this cycle, split by location, where allocated_credits and used_credits are the client's credit pool, shared by all of their locations, beside used_here for what that location alone spent and pool_workspace_id for which pool it draws on. A key bound to a single location reads its own locations only and never the account's credit pool behind them; group the rows by pool_workspace_id and read each pool once, because the siblings of a client repeat the same allocated_credits and used_credits and adding the rows up overcounts; allocated_credits is the monthly allocation and cycle_topup_credits any one-off extra credits given for this cycle only, so the cap this cycle is both added together.

Workspace keyusage:readread
Response fields
dataobject
data.account_idstring
data.planstring
data.cycle_startstring
data.cycle_endstring
data.credits_allowanceinteger
data.credits_burnedinteger
data.credits_remaininginteger
data.automation_pausedboolean
data.workspacesarray
data.workspaces[].idstring
data.workspaces[].namestring
data.workspaces[].allocated_creditsinteger
data.workspaces[].cycle_topup_creditsinteger
data.workspaces[].used_creditsinteger
data.workspaces[].used_hereinteger
data.workspaces[].pool_workspace_idstring
data.workspaces[].cap_modestring
data.workspaces[].automation_pausedboolean
data.workspaces[].paused_reasonnull

Failure modes and quotas: Errors · Rate limits

Events #

The activity trail, pulled rather than pushed.

GET

List events

GET /v1/events

Walk the activity trail, newest first, with a cursor. These are the same events an outbound webhook delivers, so a system that cannot take a webhook can poll instead.

Workspace keyevents:readread
NameInTypeDescription
workspace_idquerystring
optional
Only events about a single location. A key bound to one is narrowed to its own whether it names it or not. ws_4q8n1v6z0c3r7t2y5u9i
typequerystring
optional
Only events of this kind, matched on the trail's own verb. reply_sent
sincequeryISO 8601 timestamp
optional
Only events at or after this moment. 2026-09-01T00:00:00.000Z
cursorquerystring
optional
The next_cursor from the previous page. MjAyNi0wOS0xM1QxNjowMjoxMS4wMDBafGV2dF8x
limitqueryinteger
optional
Page size, 1 to 200. Defaults to 50. 50
Response fields
dataarray
data[].idstring
data[].typestring
data[].account_idstring
data[].workspace_idstring
data[].actorobject
data[].actor.kindstring
data[].actor.namestring
data[].objectstring
data[].detailobject
data[].detail.labelstring
data[].detail.kindstring
data[].detail.workspace_idsarray
data[].created_atstring
has_moreboolean
next_cursorstring

Failure modes and quotas: Errors · Rate limits

Calls

The calls your locations answered, with transcripts, messages and bookings. Free reads, in minutes.


Calls #

One row per call, newest first. Durations are minutes; no figure here is in credits, and no recording is served. The field test_call is true for a test call made in the browser from the agent builder: its minutes count like any call's, and it is left out of the daily usage totals.

GET

List calls

GET /v1/calls

List the calls of the locations this key covers, newest first across every region, with a cursor. Name workspace_ids to narrow the list; an id this key does not reach answers 404, never 403.

Workspace keycalls:read
NameInTypeDescription
workspace_idsquerystring
optional
Comma-separated location ids, or the parameter repeated. Omit it for every location the key covers. An agency's key does not cover its clients' locations: a client's calls are read with the client's own key. ws_4q8n1v6z0c3r7t2y5u9i
flaggedqueryboolean
optional
true lists flagged calls only. false, or leaving it out, lists every call. false
cursorquerystring
optional
The next_cursor from the previous page. It is bound to the same workspace_ids and flagged, and a cursor from another query answers 422. eyJ2IjoyLCJoIjoiYzFmIn0
limitqueryinteger
optional
Page size, 1 to 100. Defaults to 50. Above 100 answers 422. 50
Response fields
dataarray
data[].idstring
data[].workspace_idstring
data[].agent_idstring
data[].agent_versioninteger
data[].number_idstring
data[].directionstring
data[].statusstring
data[].started_atstring
data[].ended_atstring
data[].duration_secondsinteger
data[].minutesnumber
data[].from_numberstring
data[].to_numberstring
data[].caller_namestring
data[].languagestring
data[].outcomestring
data[].summarystring
data[].flaggedboolean
data[].flag_reasonnull
data[].transferredboolean
data[].has_recordingboolean
data[].unread_messagesinteger
data[].test_callboolean
has_moreboolean
next_cursorstring

Failure modes and quotas: Errors · Rate limits

GET

Read one call

GET /v1/calls/:id

Read one call with its transcript, the messages the caller left, the bookings it made and the fields the agent collected. The call must belong to the location you name, else 404.

Workspace keycalls:read
NameInTypeDescription
idpathstring
required
The call id. cll_5u9i4q8n1v6z0c3r7t2y
workspace_idquerystring
required
The location the call belongs to. ws_4q8n1v6z0c3r7t2y5u9i
Response fields
idstring
workspace_idstring
agent_idstring
agent_versioninteger
number_idstring
directionstring
statusstring
started_atstring
ended_atstring
duration_secondsinteger
minutesnumber
from_numberstring
to_numberstring
caller_namestring
languagestring
outcomestring
summarystring
flaggedboolean
flag_reasonnull
transferredboolean
has_recordingboolean
unread_messagesinteger
test_callboolean
ended_reasonstring
transfer_minutesnull
transcriptarray
transcript[].rolestring
transcript[].at_secondsinteger
transcript[].textstring
transcript[].toolsarray
messagesarray
messages[].idstring
messages[].call_idstring
messages[].workspace_idstring
messages[].caller_namestring
messages[].caller_numberstring
messages[].bodystring
messages[].urgencystring
messages[].statusstring
messages[].created_atstring
messages[].updated_atstring
bookingsarray
bookings[].idstring
bookings[].starts_atstring
bookings[].ends_atstring
bookings[].time_zonestring
bookings[].statusstring
bookings[].calendar_syncstring
bookings[].assignee_namenull
bookings[].caller_namestring
bookings[].caller_numberstring
bookings[].caller_emailnull
bookings[].notesstring
extractedobject
extracted.goalobject
extracted.goal.primarystring
extracted.goal.objectivenull
extracted.goal.achievedboolean
extracted.assignmentsarray

Failure modes and quotas: Errors · Rate limits

Webhooks

Push the same events the events endpoint serves to an endpoint of your own, signed and retried for 24 hours.


Subscriptions #

Endpoints this account delivers to.

GET

List subscriptions

GET /v1/webhooks

List the endpoints this account is subscribed with. A key bound to a single location sees only subscriptions whose allowlist is entirely inside its own; an account-wide subscription belongs to the account and is invisible to it.

Workspace keywebhooks:write
Response fields
dataarray
data[].idstring
data[].urlstring
data[].eventsarray
data[].workspace_idsarray
data[].statusstring
data[].secret_hintstring
data[].failing_sincenull
data[].last_success_atstring
data[].created_atstring
data[].previous_secret_expires_atnull
has_moreboolean
next_cursornull

Failure modes and quotas: Errors · Rate limits

POST

Create a subscription

POST /v1/webhooks

Subscribe an endpoint to one or more events and get its signing secret once. The secret is stored encrypted and is never shown again.

Workspace keywebhooks:writeIdempotent
NameInTypeDescription
urlbodystring
required
An absolute https URL. Plain http is refused rather than downgraded. https://hooks.example.com/robo
eventsbodystring[]
optional
Which events to receive. Omit it, or send ["*"], for all of them. Call events: there is no set order between the events of one call. call.failed means the call could not be completed or its record could not be retrieved, and that call never turns into call.completed later. call.message_taken and call.booking_created are sent after the call ends and carry the message or booking as it was at that moment, a snapshot: a message may already be marked read. Both carry caller details (number, name, email, message text), so the endpoint that receives them must protect them. Call events of a client's location reach only subscriptions made with a location key that client created; agency keys and keys the agency made for that location get none of them. location.created,credits.low
workspace_idsbodystring[]
optional
Narrow the subscription to some locations. Ignored on a key bound to a single location, which is pinned to its own. ws_4q8n1v6z0c3r7t2y5u9i
secretbodystring
optional
Bring your own signing secret instead of having one minted. whsec_your_own_secret_value
Response fields
dataobject
data.idstring
data.created_atstring
secretstring
warningstring

Failure modes and quotas: Errors · Rate limits

DELETE

Delete a subscription

DELETE /v1/webhooks/:id

Remove a subscription and stop delivering to it. A subscription this key may not see answers 404 rather than 403, so the refusal cannot confirm that somebody else's endpoint exists.

Workspace keywebhooks:writeIdempotent
NameInTypeDescription
idpathstring
required
The subscription id. whs_3r7t2y5u9i4q8n1v6z0c
Response fields
dataobject
data.idstring
data.deletedboolean

Failure modes and quotas: Errors · Rate limits

POST

Send a test delivery

POST /v1/webhooks/:id/test

Send one signed test delivery to a subscription and report what came back. It is targeted at the named subscription and never fans out to the rest of the account.

Workspace keywebhooks:writeIdempotent
NameInTypeDescription
idpathstring
required
The subscription to send to. whs_3r7t2y5u9i4q8n1v6z0c
Response fields
dataobject
data.queuedinteger

Failure modes and quotas: Errors · Rate limits

Clients

Tell us about a sale you made somewhere else, and the client location, plan, allocation and invite are created for you. Needs an agency account: a key bound to a single location has no book of clients to reach and is refused.


Clients #

A book of client locations on one account.

GET

List clients

GET /v1/clients

List the client locations on this account with their plans and allocations. Keyset paged on (created_at, id), newest first.

Agency keyclients:read
NameInTypeDescription
account_idquerystring
optional
Which account to read. A key on the platform account must name one; a key on an agency account may name its own and nothing else. acc_7t2y5u9i4q8n1v6z0c3r
cursorquerystring
optional
The next_cursor from the previous page. MjAyNi0wOS0wMVQwNzoxNTozMC4wMDBafHdzXzE
limitqueryinteger
optional
Page size, 1 to 200. Defaults to 50. 50
Response fields
dataarray
data[].idstring
data[].namestring
data[].statusstring
data[].created_atstring
data[].provisioned_viastring
data[].planobject
data[].plan.idstring
data[].plan.namestring
data[].plan.price_centsinteger
data[].plan.allowanceinteger
data[].allocationobject
data[].allocation.grantedinteger
data[].allocation.pendinginteger
data[].allocation.statusstring
data[].userobject
data[].user.idstring
data[].user.emailstring
data[].user.attachedstring
data[].inviteobject
data[].invite.holdnull
data[].subscriptionobject
data[].subscription.statusstring
data[].subscription.processorstring
data[].subscription.external_referencestring
data[].subscription.current_period_endstring
data[].subscription.canceled_atnull
data[].suspend_atnull
has_moreboolean
next_cursornull

Failure modes and quotas: Errors · Rate limits

POST

Create a client

POST /v1/clients

Create a client location on a retail plan. The sale is never refused: a credit pool that cannot back the allocation answers 201 with waiting_credits rather than an error, because the money already changed hands.

Agency keyclients:writeIdempotent
NameInTypeDescription
account_idbodystring
optional
Which account the client belongs to. A key on the platform account must name one; a key on an agency account may name its own and nothing else. acc_7t2y5u9i4q8n1v6z0c3r
emailbodystring
optional
The client's email. A user is created and invited when it is free, and attached when it already belongs to them. owner@haldenbakery.example
namebodystring
optional
The client's own name, used in the invite. Halden Bakery
workspace_namebodystring
optional
What to call the location. Defaults to the client's name. Halden Bakery
plan_idbodystring
optional
One of your own retail plans. Either this or a custom plan object is required. rpl_6z0c3r7t2y5u9i4q8n1v
planbodyobject
optional
A one-off plan: price_cents, allowance, and an optional name. This is the only endpoint where a caller may state a price and a number of credits outright. [object Object]
external_referencebodystring
optional
Your own id for the sale. It makes a retry safe beyond the 24-hour idempotency window. AP-88214
processorbodystring
optional
The processor you were paid through, in your own vocabulary. Defaults to api. acmepay
period_endbodyISO 8601 timestamp
optional
When the period you charged for ends. 2026-10-01T07:15:30.000Z
retail_price_centsbodyinteger
optional
What you charged, in cents, when it differs from the plan's list price. 9900
require_backingbodyboolean
optional
Measure the credit pool first and refuse an unbacked client, for a partner who calls before charging. Defaults to false. false
Response fields
idstring
createdboolean
statusstring
planobject
plan.idstring
plan.namestring
plan.price_centsinteger
plan.allowanceinteger
allocationobject
allocation.requestedinteger
allocation.grantedinteger
allocation.statusstring
allocation.short_byinteger
userobject
user.idstring
user.emailstring
user.attachedstring
inviteobject
invite.statusstring
invite.expires_atnull

Failure modes and quotas: Errors · Rate limits

GET

Read one client

GET /v1/clients/:id

Read one client location with its plan, allocation and usage. A client belonging to another agency answers 404, never 403.

Agency keyclients:read
NameInTypeDescription
idpathstring
required
The client location id. ws_0c3r7t2y5u9i4q8n1v6z
account_idquerystring
optional
Which account to read. A key on the platform account must name one. acc_7t2y5u9i4q8n1v6z0c3r
Response fields
idstring
namestring
statusstring
created_atstring
provisioned_viastring
planobject
plan.idstring
plan.namestring
plan.price_centsinteger
plan.allowanceinteger
allocationobject
allocation.grantedinteger
allocation.pendinginteger
allocation.statusstring
userobject
user.idstring
user.emailstring
user.attachedstring
inviteobject
invite.holdnull
subscriptionobject
subscription.statusstring
subscription.processorstring
subscription.external_referencestring
subscription.current_period_endstring
subscription.canceled_atnull
suspend_atnull

Failure modes and quotas: Errors · Rate limits

POST

Resend a client invite

POST /v1/clients/:id/invite

Invite a person to a client location by email. Re-minting revokes every unused link, so there is exactly one working invite afterwards, and the token itself never appears in a response.

Agency keyclients:writeIdempotent
NameInTypeDescription
idpathstring
required
The client location id. ws_0c3r7t2y5u9i4q8n1v6z
account_idbodystring
optional
Which account the client belongs to. A key on the platform account must name one. acc_7t2y5u9i4q8n1v6z0c3r
Response fields
sentboolean
expires_atstring
hoststring

Failure modes and quotas: Errors · Rate limits

POST

Cancel a client

POST /v1/clients/:id/cancel

Cancel a client location at the end of its period or right away. Nothing is cut off at once: suspension is parked at the period end plus the platform's grace, and a sweep applies it.

Agency keyclients:writeIdempotent
NameInTypeDescription
idpathstring
required
The client location id. ws_0c3r7t2y5u9i4q8n1v6z
account_idbodystring
optional
Which account the client belongs to. A key on the platform account must name one. acc_7t2y5u9i4q8n1v6z0c3r
at_period_endbodyboolean
optional
Defaults to true. False means the grace runs from now rather than from the end of the paid period, not that access stops immediately. true
period_endbodyISO 8601 timestamp
optional
Override the period end the subscription row holds. 2026-10-01T07:15:30.000Z
reasonbodystring
optional
Kept on the activity row. Defaults to api_cancel. card_declined
Response fields
idstring
statusstring
suspend_atstring
period_endstring

Failure modes and quotas: Errors · Rate limits

POST

Reactivate a client

POST /v1/clients/:id/reactivate

Bring a canceled client location back onto a plan. The pending suspension is cleared, the subscription goes back to active, and the plan's credits are requested again from the credit pool.

Agency keyclients:writeIdempotent
NameInTypeDescription
idpathstring
required
The client location id. ws_0c3r7t2y5u9i4q8n1v6z
account_idbodystring
optional
Which account the client belongs to. A key on the platform account must name one. acc_7t2y5u9i4q8n1v6z0c3r
period_endbodyISO 8601 timestamp
optional
The new period end to record on the subscription. 2026-11-01T07:15:30.000Z
Response fields
idstring
statusstring
suspend_atnull
allocationobject
allocation.grantedinteger
allocation.pendinginteger

Failure modes and quotas: Errors · Rate limits

POST

Set a client allocation

POST /v1/clients/:id/allocation

Set how many credits a client may burn this cycle: the allocation is their credit pool, shared by all of their locations, so naming any of their locations sets the same number. Unlike a sale, this one is refused when the account's credit pool cannot back it: nobody has paid anybody, so there is still something to say no to.

Agency keyclients:writecredits:allocateIdempotent
NameInTypeDescription
idpathstring
required
The client location id. ws_0c3r7t2y5u9i4q8n1v6z
account_idbodystring
optional
Which account the client belongs to. A key on the platform account must name one. acc_7t2y5u9i4q8n1v6z0c3r
creditsbodyinteger
required
The new allocation on the client's credit pool, a whole number of credits, zero or more. It is an allocation and not a transfer: no credits move. 3000
Response fields
workspace_idstring
allocated_creditsinteger
total_allocatedinteger
pool_balanceinteger
pool_workspace_idstring
zeroed_workspace_idsarray

Failure modes and quotas: Errors · Rate limits

Accounts and workspaces

The provisioning surface: accounts, the workspaces under them, and what each has spent. Usage reads and the workspace create reach an agency key.


Accounts #

Top-level tenants.

GET

Read account usage

GET /v1/accounts/:id/usage

Read one account's credits bought and burned this cycle, split by location, where allocated_credits and used_credits are the client's credit pool, shared by all of their locations, and used_here is what that location alone spent. A key on an agency account may read its own account and no other; group the rows by pool_workspace_id and read each pool once, because the siblings of a client repeat the same allocated_credits and used_credits and adding the rows up overcounts; allocated_credits is the monthly allocation and cycle_topup_credits any one-off extra credits given for this cycle only, so the cap this cycle is both added together.

Agency keyread
NameInTypeDescription
idpathstring
required
The account id. acc_7t2y5u9i4q8n1v6z0c3r
Response fields
account_idstring
planstring
cycle_startstring
cycle_endstring
credits_allowanceinteger
credits_purchasedinteger
credits_burnedinteger
credits_remaininginteger
ai_pausedboolean
workspacesarray
workspaces[].idstring
workspaces[].namestring
workspaces[].allocated_creditsinteger
workspaces[].cycle_topup_creditsinteger
workspaces[].used_creditsinteger
workspaces[].used_hereinteger
workspaces[].pool_workspace_idstring

Failure modes and quotas: Errors · Rate limits

Workspaces #

The locations under an account.

POST

Create a workspace

POST /v1/workspaces

Add a location to an account with an optional credit allocation. A key on the platform account says which account; a key on an agency account cannot, because there is only one it could mean.

Agency keyworkspaces.write
NameInTypeDescription
account_idbodystring
optional
Which account. Required on a key on the platform account, refused on a key on an agency account naming another. acc_7t2y5u9i4q8n1v6z0c3r
namebodystring
required
What the location is called. Halden Bakery
allocated_creditsbodyinteger
optional
The credits this location may burn this cycle. Defaults to 0. 2000
retail_price_centsbodyinteger
optional
What the location is sold for, in cents. <code>retail_price</code> is accepted as a synonym. 9900
referencebodystring
optional
Your own id for the sale, which is what makes a retry return the same location. order-88215
Response fields
idstring
account_idstring
namestring
statusstring
allocated_creditsinteger
used_creditsinteger
createdboolean

Failure modes and quotas: Errors · Rate limits

GET

Read workspace usage

GET /v1/workspaces/:id/usage

Read what a single location burned this cycle and how much of the allocation is left, the allocation being the client's credit pool, shared by all of their locations, with used_here for what this location alone spent; allocated_credits is the monthly allocation and cycle_topup_credits any one-off extra credits given for this cycle only, so the cap this cycle is both added together.

Agency keyread
NameInTypeDescription
idpathstring
required
The location id. ws_0c3r7t2y5u9i4q8n1v6z
Response fields
workspace_idstring
namestring
statusstring
cycle_startstring
cycle_endstring
allocated_creditsinteger
cycle_topup_creditsinteger
used_creditsinteger
remaining_creditsinteger
used_hereinteger
pool_workspace_idstring

Failure modes and quotas: Errors · Rate limits

Credits

The credit pool and the allocations against it. Granting adds credits and is ours alone; allocating moves no credits at all, it sets what a location may spend.


Credits #

Grants and allocations.

POST

Allocate credits

POST /v1/credits/allocate

Set a client's allocation against the account's credit pool, which moves no credits: the allocation is their credit pool, shared by all of their locations, whichever of those locations the request names. It is refused when the account's credit pool cannot back the new allocation, so the allocations can never promise more than the pool holds.

Agency keycredits.allocatecredits.write
NameInTypeDescription
workspace_idbodystring
required
Any location of the client to allocate to. Their whole credit pool is set, whichever of their locations is named. ws_0c3r7t2y5u9i4q8n1v6z
creditsbodyinteger
required
The new allocation on the client's credit pool, a whole number of credits, zero or more. 3000
Response fields
workspace_idstring
allocated_creditsinteger
total_allocatedinteger
pool_balanceinteger
pool_workspace_idstring
zeroed_workspace_idsarray

Failure modes and quotas: Errors · Rate limits

Assistants

The same surface over the Model Context Protocol, so an AI assistant can use these endpoints as tools. One stateless POST endpoint, authenticated with the very same key.


Model Context Protocol #

JSON-RPC over one HTTP endpoint.

POST

Model Context Protocol endpoint

POST /mcp

Answer Model Context Protocol requests so an AI assistant can use the endpoints above as tools. Every tool dispatches to one of the paths above with the caller's own key, so the scopes, tenancy, rate limits, credits and idempotency are the same ones a direct call gets.

Workspace keyread
NameInTypeDescription
MCP-Protocol-Versionheaderstring
optional
The negotiated protocol version. Absent on the first message, where initialize carries the ask instead. 2025-06-18
jsonrpcbodystring
required
Always the literal 2.0. 2.0
idbodystring or integer
optional
The request id. Omit it for a notification, which is answered 202 with no body. 1
methodbodystring
required
initialize, tools/list, tools/call, resources/list, resources/read, prompts/list or prompts/get. tools/call
paramsbodyobject
optional
The method's arguments. For tools/call: a name and an arguments object. [object Object]
Response fields
jsonrpcstring
idinteger
resultobject
result.contentarray
result.content[].typestring
result.content[].textstring

Failure modes and quotas: Errors · Rate limits

Provisioning hooks

A signed endpoint a cart, a checkout or an affiliate network POSTs to when one of your clients buys, renews, fails a payment, cancels or refunds. No key: each hook has its own secret, minted on the Developers screen, and the signature is over the timestamp and the raw body.


Inbound hook #

One endpoint per hook, with a product-to-plan map behind it.

POST

Receive a provisioning event

POST /webhooks/provisioning/:hook_id

Record a sale, a renewal, a failed payment, a cancellation or a refund your own gateway made, and provision, extend or suspend the client location behind it. Authenticated by an HMAC over the timestamp and the raw body rather than by an API key, so no scope applies.

Agency key
NameInTypeDescription
hook_idpathstring
required
The hook's own id, part of the URL you copied out of the Developers screen. phk_9i4q8n1v6z0c3r7t2y5u
X-Signature-V2headerstring
optional
sha256= followed by the hex HMAC-SHA256, under the hook's secret, of the X-Timestamp value exactly as you send it, a period, and the raw request body: HMAC(secret, timestamp + "." + body). Use this one. When it is present it alone is checked, so a wrong V2 is refused even if X-Signature-256 is right. sha256=3c9e7a1f5b20d84e6a17c0f9b2d5e83a41f6c07b9d2e58a3f1c46b0e7d92a5f8
X-Signature-256headerstring
optional
The older signature: sha256= followed by the hex HMAC-SHA256 of the raw request body alone under the hook's secret. Still accepted when X-Signature-V2 is absent (an empty X-Signature-V2 header counts as present and is judged, and refused, as V2), but it does not cover the timestamp, so a captured request can be replayed with a fresh one inside the 5-minute window. Move to X-Signature-V2: once every sender has, this header is refused. sha256=8f4b1c2d0e7a63958142b0cd7e3f9a25c6b81d04e72f5a396c0b1d8e4a7f2c53
X-TimestampheaderISO 8601 timestamp or unix seconds
required
When you sent it. More than 5 minutes either side of our clock is refused, which is what stops a captured request being useful tomorrow. X-Signature-V2 signs this exact value, so it cannot be changed in transit. 2026-09-14T10:04:22.000Z
eventbodyenum: purchase | rebill | payment_failed | cancel | refund
required
What happened. rebill extends the paid period by one interval and clears a failed payment; payment_failed marks the client past due and starts the grace period before suspension. purchase
external_idbodystring
required
Your own id for the sale, the same one on every event about it. One claim is kept per event per id for purchase, cancel and refund, so a redelivery is answered as a duplicate rather than provisioning twice. A rebill and a payment_failed happen again and again under this same id, so those 2 are claimed per event_id instead. AP-88214
event_idbodystring
optional
Your processor's own id for THIS renewal or THIS decline, usually the invoice or transaction id. It is what makes one month distinct from the next under the same external_id: a redelivery carrying the same event_id is answered as a duplicate, a new month with a new event_id is acted on. Leave it out on a rebill or a payment_failed and the request is refused. INV-88214-03
product_idbodystring
optional
Your product id, on a purchase. It is looked up in this hook's own plan map. starter-monthly
emailbodystring
optional
The buyer's email, on a purchase. The client user is created or attached from it. owner@haldenbakery.example
namebodystring
optional
The buyer's name, on a purchase. Halden Bakery
intervalbodyenum: month | year
optional
How often this sale is charged, on a purchase or a rebill. Leave it out and the sale is monthly. Send year and every rebill of it moves the paid period forward 12 months instead of 1. We read your processor's own wording: month, monthly, m and 1 all mean monthly; year, yearly, annual, annually, y and 12 all mean yearly, in any case. A word we do not recognize is treated as monthly and the sale still goes through, with the value we dropped written to your account activity so you can correct it. On a rebill it is how you move a client who has switched to annual billing: the cadence is rewritten and that renewal already runs a year. On a cancel, a refund or a payment_failed it is ignored. year
period_endbodyISO 8601 timestamp
optional
When the period you charged for ends, as an ISO 8601 timestamp. On a purchase and a rebill it has to be in the future. On a rebill, leave it out and we extend the stored period end by one interval of this sale: 1 month for a monthly sale, 12 months for a yearly one. 2026-10-01T07:15:30.000Z
amount_centsbodyinteger
optional
What the processor tried to take, on a payment_failed. The client's stored retail price is used when you leave it out. 7900
Response fields
receivedboolean
workspace_idstring
createdboolean
statusstring

Failure modes and quotas: Errors · Rate limits

Robofono API reference. Select an endpoint to see code samples and try it in the console.