# 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: the Sypnia engine (open source, self-hosted) and Sypnia Cloud (paid service). Status: at launch.  
Source: https://docs.sypnia.com/api/overview-and-authentication/

For agents: Read this first before calling the Sypnia HTTP API: base URLs for Cloud and self-hosted, ingest key vs API token vs root token, scopes, the project parameter, and the whoami, summary and search endpoints.

**\[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:

```bash
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](https://docs.sypnia.com/api/ingest) and [OTLP](https://docs.sypnia.com/api/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`](https://docs.sypnia.com/api/projects-keys-and-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:

```bash
curl "https://sypnia.example.com/v1/problems?project=shop" \
  -H "Authorization: Bearer $SYPNIA_ROOT_TOKEN"
```

> **Warning: Keep the root token for setup**
>
> Use the root token to create projects and their first tokens, then work with API tokens. A root token in a script, an agent's configuration or a CI job can delete every project.

## What the engine has, and what only Sypnia Cloud has

|                                             | Sypnia engine (open source, self-hosted)              | Sypnia Cloud (paid 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](https://docs.sypnia.com/api/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` \[Engine, Cloud]

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:**

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

**Response (200):**

```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` \[Engine, Cloud]

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, default `production`): The environment to read. Any name the project has sent, or `all`.
- `since` (string, optional, default `24h`): Start of the period that counts as «now». An ISO 8601 timestamp or a relative value, from `1h` to `7d`.

**Request:**

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

**Response (200):**

```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` \[Engine, Cloud]

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()`.

**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, default `production`): The environment to read. Any name the project has sent, or `all`.
- `q` (string, up to 120 characters, required): The text to look for. 2 to 120 characters.
- `types` (string, optional, default `problems,sessions,people,accounts,traces,releases,pages`): Comma-separated list of what to look in.
- `since` (string, optional, default `30d`): Only sessions, traces and activity after this moment count.
- `limit` (integer, 1 to 25, optional, default `10`): Most results per type.

**Request:**

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

**Response (200):**

```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:**

- `400` `invalid_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](https://docs.sypnia.com/api/errors-limits-pagination).
