Docs

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.

Applies to EngineCloud At launch

View as Markdown
On this page
  1. Base URL
  2. Authentication
  3. Scopes of an API token
  4. The project parameter
  5. What the engine has, and what only Sypnia Cloud has
  6. Conventions
  7. The three endpoints that span a project
  8. Check a credential
  9. What is failing right now
  10. Search a 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

WhereRead and manageSend data (ingest, OTLP)
Sypnia Cloudhttps://api.sypnia.com/v1https://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:

Terminal
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.

CredentialLooks likeSecret?What it can doWhere it exists
Ingest keyspk_ and 32 hex charactersNo. It ships in your appSend data, and nothing else. Accepted only by the ingest and OTLP endpointsEngine and Cloud
API tokensps_ and 40 charactersYesRead and manage one project, within its scopesEngine and Cloud
Root tokenAny string of 32 characters or more that you chooseYesEverything, on every project of the engineEngine only. Set with SYPNIA_ROOT_TOKEN

Scopes of an API token

ScopeWhat it allows
readRead 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
replayFetch replay recordings and page snapshots. They show the page as the person saw it, so this scope is separate
adminEverything 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:

Terminal
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

The Sypnia engine and Sypnia Cloud compared
Sypnia engineOpen source, self-hostedSypnia CloudPaid service, with a free tier
Projects, ingest keys, API tokensYes, through this APIYes. Projects are created in the app
Users, organizations, roles, plans, billingDo not existIn the app. No public API at launch
Pull requestsNot in the engine: 404 cloud_onlyPOST /v1/problems/{problem}/pull-request
LimitsNone set by us. Optional quotas in your configurationYour 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": … }. Pass next_cursor back as cursor.
  • Time ranges use since and until: a timestamp, or a relative value such as 24h or 7d.
  • Environment: read endpoints take environment, default production.
  • 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

GET /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.

Authentication
Any credential

Request

Terminal
curl https://api.sypnia.com/v1/whoami \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"

Response200

JSON
{
  "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

GET /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.

Authentication
API token (read)

Query parameters

  • project
    string optional

    The 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.

  • environment
    string optional

    The environment to read. Any name the project has sent, or all.

    Default: production

  • since
    string optional

    Start of the period that counts as «now». An ISO 8601 timestamp or a relative value, from 1h to 7d.

    Default: 24h

Request

Terminal
curl "https://api.sypnia.com/v1/summary" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"

Response200

JSON
{
  "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

GET /v1/search EngineCloud

Finds problems, sessions, people, accounts, traces, releases and pages by one text. Matching ignores case and accents.

What you typeWhat 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 moreThat session or trace
A person’s id, name or e-mail; an account’s id or nameThe 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().

Authentication
API token (read)

Query parameters

  • project
    string optional

    The 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.

  • environment
    string optional

    The environment to read. Any name the project has sent, or all.

    Default: production

  • q
    string, up to 120 characters required

    The text to look for. 2 to 120 characters.

  • types
    string optional

    Comma-separated list of what to look in.

    Default: problems,sessions,people,accounts,traces,releases,pages

  • since
    string optional

    Only sessions, traces and activity after this moment count.

    Default: 30d

  • limit
    integer, 1 to 25 optional

    Most results per type.

    Default: 10

Request

Terminal
curl "https://api.sypnia.com/v1/search?q=pay+button" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"

Response200

JSON
{
  "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

  • 400invalid_request

    q is 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.

Sections

Start hereWhat Sypnia is, how it works, what is open source and what is the paid cloud, and the two ways to get your first problem in plain words.ConceptsThe ten ideas Sypnia is made of, each defined precisely, from a project and its keys to problems, traces and alerts.SDKsHow your app sends data to Sypnia. One SDK for the browser, one for Node, one for Next.js, and the OpenTelemetry intake for every other backend.The agentHow Sypnia analyses a problem, what it writes, what it sends to a model and what it never does.MCP and skillsConnect your coding agent to Sypnia so it can ask what is failing in production, read what it needs to fix it, and set Sypnia up for you.API referenceThe Sypnia HTTP API: one API for the open-source engine and for Sypnia Cloud, with every endpoint, parameter, response and error.CLI referenceThe sypnia command: how to install it, the variables it reads, what its exit codes mean, and where each command is documented.Self-hostingWhat you run when you host the Sypnia engine yourself, what you need, what it costs, and what you do not get compared with Sypnia Cloud.How the engine is builtThe whole Sypnia engine on one page, from a click in your app to the sentence your coding agent reads, with the design rules and the code that holds them.Sypnia CloudHow the paid service works, from organizations and roles to plans, limits, billing, where your data lives, the GitHub App and support.Privacy and securityWhat Sypnia collects from your app and its users, what it never collects, how masking works, how to delete data, and how the service is protected.LicensingWhich licence covers each part of Sypnia, what you may do with it, how the name may be used, and the terms of a contribution.GuidesStep-by-step recipes for the common ways to use Sypnia, from apps made with AI builders and Next.js on Vercel to Supabase, source maps in CI, alert e-mails from your own engine, and moving from Sentry.ReferenceThe pages you look things up in, from the event schema and the glossary to what is planned, the changelog and the common questions.
↑↓ to move↵ to openEsc to close