Overview and authentication
The base URL, the three kinds of credential and what each may do, and the three endpoints that span a whole project.
Engine Cloud The Sypnia API is one HTTP API for the open-source engine and for Sypnia Cloud. Sypnia Cloud is the same engine, run by us, so an endpoint behaves the same in both. The few that exist in only one carry a badge.
Everything the app, the Console, the MCP server and the CLI show comes from this API. Its machine-readable contract is spec/openapi.yaml in the docs repository (OpenAPI 3.1).
Base URL
| Where | Read and manage | Send data (ingest, OTLP) |
|---|---|---|
| Sypnia Cloud | https://api.sypnia.com/v1 | https://ingest.sypnia.com/v1 |
| Self-hosted engine | <your base URL>/v1 | <your base URL>/v1 |
A self-hosted engine serves everything from the one address you set in SYPNIA_BASE_URL, with the same paths. The examples in this reference use the Sypnia Cloud addresses; replace the host to use them against your engine.
Requests and responses are JSON in UTF-8. Send Content-Type: application/json with a body. Only HTTPS is accepted on Sypnia Cloud.
Authentication
Send the credential in the Authorization header:
curl https://api.sypnia.com/v1/problems \
-H "Authorization: Bearer $SYPNIA_API_TOKEN"There are three kinds of credential. The engine has no users and no passwords.
| Credential | Looks like | Secret? | What it can do | Where it exists |
|---|---|---|---|---|
| Ingest key | spk_ and 32 hex characters | No. It ships in your app | Send data, and nothing else. Accepted only by the ingest and OTLP endpoints | Engine and Cloud |
| API token | sps_ and 40 characters | Yes | Read and manage one project, within its scopes | Engine and Cloud |
| Root token | Any string of 32 characters or more that you choose | Yes | Everything, on every project of the engine | Engine only. Set with SYPNIA_ROOT_TOKEN |
Scopes of an API token
| Scope | What it allows |
|---|---|
read | Read everything except replay content. Its only writes are reversible marks that are recorded with the token’s name: resolve or reopen a problem, acknowledge an alert, set a suggestion’s status |
replay | Fetch replay recordings and page snapshots. They show the page as the person saw it, so this scope is separate |
admin | Everything that changes the project: keys, tokens, settings, releases and source maps, uptime checks, alert rules, webhooks, ignoring a problem, deleting data, asking for an analysis or a pull request |
Scopes do not include each other. A token for a coding agent needs read. A token for your CI, to upload source maps, needs admin. Each endpoint in this reference says which scope it needs.
Create tokens with POST /v1/tokens, with sypnia token create, or in the app on Sypnia Cloud. A token’s secret is shown once.
The project parameter
An API token belongs to one project, so you never say which project you mean. The root token can see every project, so with it you must add project (the id or the slug) to every call that works on one project:
curl "https://sypnia.example.com/v1/problems?project=shop" \
-H "Authorization: Bearer $SYPNIA_ROOT_TOKEN"What the engine has, and what only Sypnia Cloud has
| Sypnia engineOpen source, self-hosted | Sypnia CloudPaid service, with a free tier | |
|---|---|---|
| Projects, ingest keys, API tokens | Yes, through this API | Yes. Projects are created in the app |
| Users, organizations, roles, plans, billing | Do not exist | In the app. No public API at launch |
| Pull requests | Not in the engine: 404 cloud_only | POST /v1/problems/{problem}/pull-request |
| Limits | None set by us. Optional quotas in your configuration | Your plan's. See GET /v1/usage |
Conventions
They are the same on every endpoint and are explained once, on Errors, limits, pagination:
- Errors have one shape:
{ "error": { "code", "message", "doc_url", "request_id" } }. - Lists return
{ "data": [...], "next_cursor": … }. Passnext_cursorback ascursor. - Time ranges use
sinceanduntil: a timestamp, or a relative value such as24hor7d. - Environment: read endpoints take
environment, defaultproduction. - Timestamps are ISO 8601 in UTC. Durations are in milliseconds and end in
_ms. - Freshness: a new problem appears within 2 minutes of its first event; counts, performance numbers and the session list are complete within 10 minutes.
The three endpoints that span a project
Check a credential
/v1/whoami EngineCloud Says what the credential in the request is and what it may do. Use it to test a new token, and in scripts before a long job. It works with every credential, including an ingest key.
Request
curl https://api.sypnia.com/v1/whoami \
-H "Authorization: Bearer $SYPNIA_API_TOKEN"Response200
{
"credential": "api_token",
"id": "tok_9r4t6y2u8i1o",
"name": "Cursor",
"scopes": [
"read",
"replay"
],
"project": {
"id": "prj_5k2m9x4q7w1z",
"slug": "shop",
"name": "Shop"
},
"deployment": "cloud",
"engine_version": "1.0.0"
}What is failing right now
/v1/summary EngineCloud One answer to «what is failing in production?»: the open problems that matter most, uptime checks that are
down, pages that got slower, and how fresh the data is. It is what the MCP tool health returns and what the
daily summary of Sypnia Cloud is built from.
state is failing when a check is down or a problem opened or regressed in the period, degraded when
only older problems are open or a page got slower, and ok otherwise.
Query parameters
-
projectstring optionalThe project’s id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is
403. -
environmentstring optionalThe environment to read. Any name the project has sent, or
all.Default:
production -
sincestring optionalStart of the period that counts as «now». An ISO 8601 timestamp or a relative value, from
1hto7d.Default:
24h
Request
curl "https://api.sypnia.com/v1/summary" \
-H "Authorization: Bearer $SYPNIA_API_TOKEN"Response200
{
"project": {
"id": "prj_5k2m9x4q7w1z",
"slug": "shop",
"name": "Shop"
},
"environment": "production",
"generated_at": "2026-03-12T10:35:00Z",
"data_through": "2026-03-12T10:34:10Z",
"state": "failing",
"sentence": "1 new problem in the last 24 hours. Every uptime check is up. 1 page got slower.",
"problems": {
"open": 1,
"new": 1,
"regressed": 0,
"top": [
{
"id": "prb_8f3k2m9x4q7w",
"slug": "pay-button-does-nothing",
"sentence": "3 people tried to pay today and could not. The Pay button does nothing since yesterday's change.",
"title": "createPayment answered 400 in POST /api/checkout",
"confidence": "high",
"people": 3,
"sessions": 3,
"first_seen": "2026-03-12T09:12:04Z",
"last_seen": "2026-03-12T10:31:47Z",
"first_release": "4f2a91c",
"regressed": false
}
]
},
"uptime": {
"checks": 1,
"down": []
},
"performance": {
"slower_pages": [
{
"route": "/search",
"lcp_p75_ms": 3100,
"previous_lcp_p75_ms": 1900,
"views": 1840
}
],
"failing_api": []
},
"traffic": {
"sessions": 498,
"people": 412,
"errors": 5
},
"alerts": {
"unacknowledged": 1
}
}Search a project
/v1/search EngineCloud Finds problems, sessions, people, accounts, traces, releases and pages by one text. Matching ignores case and accents.
| What you type | What it finds |
|---|---|
Words (pay button, amount_required) | Problems by sentence, title, slug, file or function. Pages by route |
| A session id or a trace id, whole or its first 8 characters or more | That session or trace |
| A person’s id, name or e-mail; an account’s id or name | The person or account, with their latest sessions |
A release version or its beginning (4f2a) | The release |
Names and e-mails are searchable only if your app sent them with identify().
Query parameters
-
projectstring optionalThe project’s id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is
403. -
environmentstring optionalThe environment to read. Any name the project has sent, or
all.Default:
production -
qstring, up to 120 characters requiredThe text to look for. 2 to 120 characters.
-
typesstring optionalComma-separated list of what to look in.
Default:
problems,sessions,people,accounts,traces,releases,pages -
sincestring optionalOnly sessions, traces and activity after this moment count.
Default:
30d -
limitinteger, 1 to 25 optionalMost results per type.
Default:
10
Request
curl "https://api.sypnia.com/v1/search?q=pay+button" \
-H "Authorization: Bearer $SYPNIA_API_TOKEN"Response200
{
"q": "pay button",
"problems": [
{
"id": "prb_8f3k2m9x4q7w",
"slug": "pay-button-does-nothing",
"status": "open",
"sentence": "3 people tried to pay today and could not. The Pay button does nothing since yesterday's change.",
"title": "createPayment answered 400 in POST /api/checkout",
"people": 3,
"last_seen": "2026-03-12T10:31:47Z"
}
],
"sessions": [],
"people": [],
"accounts": [],
"traces": [],
"releases": [],
"pages": []
}Errors
- 400
invalid_requestqis missing, shorter than 2 characters or longer than 120.
The errors every endpoint can answer (401, 403, 429, 500, 503) are on Errors, limits, pagination.