API

API overview

The Signalbox API. Its base address, how a call signs in, the response wrapper, rate limits and where the reference lives.

The API lets your own code do what a person does in the app. Each endpoint calls the same code as the screen, so the rules are the same.

Base address

https://api.trysignalbox.com/api/v1

The full reference, made from the code, is at api.trysignalbox.com/swagger. It lists every endpoint with its inputs and answers.

Signing in

Send your API key in the x-api-key header on every call:

curl https://api.trysignalbox.com/api/v1/me \
  -H "x-api-key: YOUR_API_KEY"

/me answers with the key’s workspace and role. Use it to check that a key works.

The workspace comes from the key. You do not name it in the address. See Authentication.

The response wrapper

Every answer has the same shape:

{
  "succeeded": true,
  "data": {
    "workspaceId": "00000000-0000-0000-0000-000000000000",
    "workspaceName": "Example Ltd",
    "role": "editor"
  },
  "messages": []
}

Part	Holds
`succeeded`	`true` when the call did what was asked, else `false`
`data`	The answer. Its shape depends on the endpoint
`messages`	A list of sentences. When a call fails, they say why

Check succeeded as well as the HTTP status.

Status codes

Status	Means
`200`	The call worked
`400`	The call was understood and refused: a value is wrong, or something it needs is missing. The message says what to do
`401`	No API key was sent, or the key is not valid
`403`	The key’s level does not allow this call, or the key may not read leads
`404`	There is no such flow, queue or lead in the key’s workspace
`429`	Too many calls. See below

Rate limits

Calls are limited for each key. Over the limit the API answers 429 Too Many Requests, with a Retry-After header that holds a number of seconds. Wait that long, then try again.

Calls with no valid key are limited for each address they come from.

What there is

Area	Calls
Workspace	Read what is set up and what is missing
Flows	List, read, make, save a draft, check, dry run, publish, pause, delete, versions, restore
Flow reference	Step types with their settings and exits, fields, templates
Forms	List, read, set which flow a form runs, turn routing on or off
Queues	List, make, change, delete, set members
Meeting types	List, make, change, delete, working hours, preview of free times
Reps	List with calendar status, email a rep their calendar link, disconnect a calendar
Sites	List, add, remove
Settings	Read, change
HubSpot	Status, start a sync, list owners, pipelines, properties and workflows
Leads	List, read one with its trace
Audit	Read

A flow read returns the flow document, an outline of the flow in words, and what the checker finds, each with how to fix it. See How a flow works.

What is left out

Some things need a person in a browser and have no endpoint:

Connecting HubSpot, and connecting a rep’s calendar.
Billing, team invites and roles, and making or deleting API keys.

Agents

An AI agent does not need to call the API itself. It connects to the MCP server on the same host, which offers the same actions as tools. See Agents.