# Introduction

Base URL, authentication, errors and rate limits for the Ensue REST API.

The API is JSON over HTTPS, under `/v1`.

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

## Authentication

Create a workspace API key in **Settings → API keys & MCP** and send it as a bearer token:

```bash
curl https://api.getensue.com/v1/sources \
  -H "authorization: Bearer ens_<key>"
```

A key can be limited to certain inboxes. A limited key can use only the agent endpoints below (pull, peek, claim, close leases, subscribe, read sources, MCP) and gets `403` anywhere else.

## Errors and limits

Errors return a JSON body with `error` (a short code such as `not_found`) and `message`. Calls are rate limited per key per minute, and the response headers show where you stand.

| Limit | Applies to |
|---|---|
| 60 a minute | Inbox pulls (`GET /agent/inbox/:id/next`) |
| 100 a minute | Agent messages sent into an inbox |
| 300 a minute | Everything else |

IDs carry a prefix: `src_` sources, `dst_` destinations and inboxes, `flw_` flows, `evt_` events, `trf_` transforms, `etp_` event types, `sub_` subscriptions, `key_` API keys, `msg_` Dispatch messages.

## Endpoints

The sidebar lists every endpoint with its parameters, a request example and a sample response. `:id` in a path is the resource ID.

## MCP

`/mcp` is the Model Context Protocol server (streamable HTTP, `POST` only), at `https://api.getensue.com/mcp`. Its tools are listed under [Subscriptions and MCP](/agents/subscriptions/#mcp-server).