> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sente.run/llms.txt
> Use this file to discover all available pages before exploring further.

# API overview

> Base URL, authentication, error format, and rate limits for the Sente API.

## Base URL

```
https://api.sente.run/v1
```

All endpoints accept and return JSON. Request bodies are validated with zod; invalid input returns `400` with the validation issues in the `error` field.

<Note>
  The dashboard at [app.sente.run](https://app.sente.run) talks to Sente through its own internal proxy (`api.sente.run/api/sente/*`, session-authenticated) — that is not the public API. Integrations always use `https://api.sente.run/v1` with an API key.
</Note>

## Authentication

Every `/v1` endpoint requires an API key. Create one on the [dashboard](https://app.sente.run) (API keys page). Keys look like `sk_sente_...` and are stored hashed — copy the key when it is shown.

Pass the key either way:

```bash theme={null}
# Authorization header
curl https://api.sente.run/v1/identities \
  -H "Authorization: Bearer sk_sente_..."

# or x-api-key header
curl https://api.sente.run/v1/identities \
  -H "x-api-key: sk_sente_..."
```

A missing key returns `401 {"error":"missing api key"}`; an unknown or revoked key returns `401 {"error":"invalid api key"}`.

Keys are **org-scoped**. Every resource belongs to the organization that created it. Requesting another org's resource returns `404` — the API never confirms that a resource exists outside your org.

## Error format

Errors are JSON objects with an `error` field. Errors your code should branch on also carry a stable `code`:

```json theme={null}
{ "error": "daily send limit reached (100 emails per 24h per org)", "code": "SEND_LIMIT_EXCEEDED", "limit": 100 }
```

| Status | Meaning                                                                                                                                                         |
| ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | Validation failed. `error` is an array of zod issues, or a message for guarded input (e.g. a webhook URL that resolves to a private address).                   |
| `401`  | Missing or invalid API key.                                                                                                                                     |
| `402`  | A monthly plan cap was reached (`PLAN_EMAIL_LIMIT_EXCEEDED`). Fixed by upgrading, not by waiting.                                                               |
| `403`  | Forbidden — currently only `CREDENTIALS_WRITE_ONLY` on connected accounts. See [Connections](/api-reference/connections).                                       |
| `404`  | Not found, or not your org's resource.                                                                                                                          |
| `409`  | Conflict — the request is valid but the resource is in a state that refuses it. Most carry a stable `code` (the identity `local-part taken` conflict does not). |
| `429`  | A rate or abuse cap was hit. Carries a `code` and the `limit`.                                                                                                  |

## Rate and abuse caps

Sente sends from a shared domain and drives real browsers, so per-org caps protect deliverability and capacity for everyone. Defaults below; plan-level caps vary — see [Limits](/trust/limits).

| Code                        | Status | What hit it                                                                                    | Default                                     |
| --------------------------- | ------ | ---------------------------------------------------------------------------------------------- | ------------------------------------------- |
| `SEND_LIMIT_EXCEEDED`       | 429    | Outbound emails per org per 24 h                                                               | 100                                         |
| `PLAN_EMAIL_LIMIT_EXCEEDED` | 402    | Outbound emails per org per billing month                                                      | plan-dependent                              |
| `IDENTITY_LIMIT_EXCEEDED`   | 429    | Identities per org                                                                             | plan-dependent (9 free / 25 pro / 100 team) |
| `RUN_LIMIT_EXCEEDED`        | 429    | Register/login/connect runs per org, daily and monthly. Failed runs don't count against quota. | plan-dependent                              |

Caps are checked before any side effect — a `429` send never reached the mail provider, a `429` run never started a browser.

## Resources

| Resource                                      | What it is                                                                                      |
| --------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| [Identities](/api-reference/identities)       | Managed email addresses your agent owns.                                                        |
| [Messages](/api-reference/messages)           | The identity's inbox and outbox, including OTP/magic-link annotations and the `wait` long-poll. |
| [Registrations](/api-reference/registrations) | Accounts Sente created at third-party apps, plus credentials and browser sessions.              |
| [Connections](/api-reference/connections)     | Accounts you already own, connected for delegated access.                                       |
| [Runs](/api-reference/runs)                   | One browser-driven register/login/connect attempt — status, human takeover, recording.          |
| [Webhooks](/api-reference/webhooks)           | Push notifications for inbound mail and run outcomes.                                           |