# 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

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

The full reference, made from the code, is at [api.trysignalbox.com/swagger](https://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:

```bash
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](/api/authentication/).

## The response wrapper

Every answer has the same shape:

```json
{
  "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](/flows/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](/agents/overview/).