API overview

The Sente API is one HTTP surface for the whole account lifecycle: connect or register an account at a third-party app, watch the run that drives it, read the verification email that lands in the account’s own inbox, and hand the logged-in session to your code. Everything below applies to every endpoint — read it once, then work from the per-resource pages.

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.

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

Authentication

Every /v1 endpoint requires an API key. Create one on the dashboard (API keys page). Keys look like sk_sente_... and are stored hashed — copy the key when it is shown, because it is never displayed again. Pass it in either header:

curl https://api.sente.run/v1/identities \
  -H "Authorization: Bearer sk_sente_..."

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

import { Sente } from "@sente-labs/sdk";

const sente = new Sente({ apiKey: process.env.SENTE_API_KEY! });
await sente.identities.list();

from sente import Sente
import os

sente = Sente(api_key=os.environ["SENTE_API_KEY"])
sente.identities.list()

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:

{ "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.
`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`.

Filter parameters are not validated against a value set. GET /v1/runs?status=nope returns [] rather than a 400 — an empty result is not proof that a filter name was spelled correctly.

Rate and abuse caps

Sente sends from a shared mail domain and drives real browsers, so per-org caps protect deliverability and browser capacity for everyone. Plan-level caps are on Limits.

Code	Status	What hit it	Cap
`SEND_LIMIT_EXCEEDED`	429	Outbound emails per org per 24 h	100
`PLAN_EMAIL_LIMIT_EXCEEDED`	402	Outbound emails per org per billing period	plan-dependent (150 free / 1000 pro / 5000 team)
`IDENTITY_LIMIT_EXCEEDED`	429	Identities per org — including one auto-provisioned by a `register`/`connect` call that omitted `identityId`	plan-dependent (9 free / 25 pro / 100 team)
`RUN_LIMIT_EXCEEDED`	429	Register/login/connect runs per org, daily and monthly	plan-dependent (free 30/day, 120/period)

Caps are checked before any side effect — a 429 send never reached the mail provider, a 429 run never started a browser. Failed runs never count against quota, so a run that fails on the app’s side costs you nothing.

A global per-org daily run brake sits underneath the plan caps, and the tighter of the two wins. On paid plans that brake, not the plan number, is usually what you hit first — it protects shared browser capacity during early access. Tell us if it’s in your way.

Check your usage

GET /v1/usage returns the plan’s caps and current consumption in one call — use it to back off before a 429 rather than after.

curl https://api.sente.run/v1/usage \
  -H "Authorization: Bearer sk_sente_..."

{
  "planId": "free",
  "emails": {
    "used": 12,
    "cap": 150,
    "periodStart": "2026-07-05T09:00:00.000Z",
    "periodEnd": "2026-08-04T09:00:00.000Z"
  },
  "identities": { "used": 3, "cap": 9 },
  "accounts": { "used": 2 },
  "runs": { "used": 41, "cap": 120 }
}

accounts.used counts registrations whose status is active and has no cap of its own — accounts are limited indirectly, by the run and identity caps.

Resources

Resource	What it is
Identities	The managed email address behind an account. Auto-provisioned when you don’t name one.
Messages	The identity’s inbox and outbox, the OTP/magic-link annotation, and the `wait` long-poll.
Registrations	Accounts at third-party apps — create, re-login, credentials, and browser sessions.
Connections	Accounts you already own, connected for delegated access.
Runs	One browser-driven register/login/connect attempt — status, human takeover, recording.
Webhooks	Push notifications for inbound mail and run outcomes.
Audit events	Insert-only trail of credential, session, and account actions.

Quickstart

One call to a working account, end to end.

Accounts

Why the account is the object and the identity is plumbing.

Limits

What blocks a run, and what each plan allows.

​Base URL

​Authentication

​Error format

​Rate and abuse caps

​Check your usage

​Resources

​Related

Quickstart

Accounts

Limits

Base URL

Authentication

Error format

Rate and abuse caps

Check your usage

Resources

Related