# Problems

> List problems, read one with its full context for fixing, get the ready prompt, and mark it resolved.

Applies to: the Sypnia engine (open source, self-hosted) and Sypnia Cloud (paid service). Status: at launch.  
Source: https://docs.sypnia.com/api/problems/

For agents: Reference of the Problems endpoints of the Sypnia HTTP API: parameters, response shapes, examples and errors.

A problem is a group of failures with one cause. The engine groups failures by fingerprint as they arrive: a
new problem appears, and can alert, within 2 minutes of its first event. The agent then writes the analysis
(`analysis`), when an AI provider is configured. Counts (`occurrences`, `people`, `sessions`) are complete
within 10 minutes.

A problem has two names. Its `id` (`prb_…`) never changes. Its `slug` is readable
(`pay-button-does-nothing`); it is first made from the technical title and replaced once by the agent's
first analysis. Every endpoint that takes a problem accepts the id, the current slug or any slug the problem
had before.

## Status

| Status     | Meaning                                               | How it changes                                                                                                |
| ---------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `open`     | It is happening, or nobody has said otherwise         | The starting status                                                                                           |
| `resolved` | Someone fixed it                                      | `POST …/resolve`. **If the failure comes back, the problem reopens by itself** and `regressed` becomes `true` |
| `ignored`  | Known and accepted. It never alerts and never reopens | `POST …/ignore`                                                                                               |

## The problem object

**Fields:**

- `id` (string, optional): The permanent id, `prb_…`.
- `slug` (string, optional): The readable name. Unique in the project. Made from the title at first, replaced once by the agent's first analysis; old slugs keep working.
- `fingerprint` (string, optional): The 16 hex characters the engine groups failures by.
- `kind` (string, optional): `error`: an exception. `failed_call`: a call that failed without an exception, either the page's call to an API or the server's call to a database or another service. A call fails when it gets no answer, answers `400`, or answers `500` or above. `timeout`: a request that never finished.
- `origin` (string, optional): Where the failure happened. A failure in the browser and the failure behind it on the server share a trace and are one problem: the deepest one is the problem, and what the person saw is evidence inside it. One of: `browser`, `server`.
- `status` (string, optional): See the status table above. One of: `open`, `resolved`, `ignored`.
- `regressed` (boolean, optional): `true` when the problem was resolved and came back.
- `title` (string, optional): The technical title: the error's name and message, with numbers and ids replaced so one cause is one title.
- `environment` (string, optional): The environment it happens in. The same failure in two environments is two problems.
- `route` (string or null, optional): The page or API route where it happens most.
- `where` (object or null, optional): The place in your code. From the analysis when there is one, else the first frame of your own code in the stack. `null` without source maps or without a stack.
- `first_seen` (timestamp, optional): The first failure.
- `last_seen` (timestamp, optional): The latest failure.
- `first_release` (string or null, optional): The release of the first failure.
- `last_release` (string or null, optional): The release of the latest failure.
- `occurrences` (integer, optional): How many times it happened, over its whole life.
- `people` (integer, optional): How many different people it hit. An identified person counts once across devices; an anonymous visitor counts by device.
- `sessions` (integer, optional): How many sessions it happened in.
- `resolved_at` (timestamp or null, optional): When it was last resolved. Kept as history after a regression.
- `resolved_by` (string or null, optional): Who resolved it: `token:<name>` for an API token, `mcp:<token name>` through the MCP server, `console`, or on Sypnia Cloud a person's e-mail.
- `resolved_in_release` (string or null, optional): The release said to carry the fix, if one was given.
- `note` (string or null, optional): The note left with the last status change.
- `analysis` (object, optional): What the agent wrote about the problem. See [How the analysis works](https://docs.sypnia.com/agent/how-the-analysis-works).
- `analysis.status` (string): `ready`: complete. `pending`: running, usually under a minute. `not_enough_evidence`: the agent described what happened and did not name a cause, because it could not support one. `failed`: the model call failed three times; it is tried again when the problem grows. `limit_reached`: the project used its analyses for today. `off`: no AI provider is configured, or the project switched the agent off.
- `analysis.sentence` (string or null): What happened, in one or two plain sentences. Present for `ready` and `not_enough_evidence`.
- `analysis.who` (string or null): Who it hit.
- `analysis.doing` (string or null): What they were trying to do.
- `analysis.since` (string or null): Since when, and whether it worked before.
- `analysis.cause` (object or null): The likely cause and what supports it. `null` when the agent did not find enough evidence.
- `analysis.cause.text` (string): The cause, in plain words.
- `analysis.cause.evidence` (array of object): One to six facts, each pointing at something you can open.
- `analysis.what_to_do` (string or null): The change to make. `null` when there is no cause.
- `analysis.confidence` (string or null): How well the evidence supports the cause. `null` when there is no cause. One of: `high`, `medium`, `low`.
- `analysis.generated_at` (timestamp or null): When this analysis was written.
- `analysis.provider` (string or null): The AI provider that ran it, as configured. On Sypnia Cloud, `openrouter`.
- `analysis.model` (string or null): The model that ran it, as the provider names it.
- `analysis.runs` (integer): How many times the problem has been analysed.
- `pull_request` (object or null, optional): Sypnia Cloud only. The pull request Sypnia opened for this problem. Always `null` on a self-hosted engine.
- `url` (URL, optional): The problem in the app (Sypnia Cloud) or in the Console (self-hosted).
- `created_at` (timestamp, optional): When the engine created the problem, within 2 minutes of `first_seen`.

## The analysis object

What the agent wrote about the problem. See [How the analysis works](https://docs.sypnia.com/agent/how-the-analysis-works).

**Fields:**

- `status` (string, optional): `ready`: complete. `pending`: running, usually under a minute. `not_enough_evidence`: the agent described what happened and did not name a cause, because it could not support one. `failed`: the model call failed three times; it is tried again when the problem grows. `limit_reached`: the project used its analyses for today. `off`: no AI provider is configured, or the project switched the agent off.
- `sentence` (string or null, optional): What happened, in one or two plain sentences. Present for `ready` and `not_enough_evidence`.
- `who` (string or null, optional): Who it hit.
- `doing` (string or null, optional): What they were trying to do.
- `since` (string or null, optional): Since when, and whether it worked before.
- `cause` (object or null, optional): The likely cause and what supports it. `null` when the agent did not find enough evidence.
- `cause.text` (string): The cause, in plain words.
- `cause.evidence` (array of object): One to six facts, each pointing at something you can open.
- `cause.evidence[].kind` (string): What kind of fact it is. One of: `stack_frame`, `release_change`, `trace`, `breadcrumb`, `timing`.
- `cause.evidence[].ref` (string): What it points at: `file:line`, `release:path`, a trace id, a breadcrumb's time, a release version.
- `cause.evidence[].text` (string): The fact.
- `what_to_do` (string or null, optional): The change to make. `null` when there is no cause.
- `confidence` (string or null, optional): How well the evidence supports the cause. `null` when there is no cause. One of: `high`, `medium`, `low`.
- `generated_at` (timestamp or null, optional): When this analysis was written.
- `provider` (string or null, optional): The AI provider that ran it, as configured. On Sypnia Cloud, `openrouter`.
- `model` (string or null, optional): The model that ran it, as the provider names it.
- `runs` (integer, optional): How many times the problem has been analysed.

## List problems

`GET /v1/problems` \[Engine, Cloud]

Problems that were seen in the time range, newest activity first. Each one carries its analysis, so a list
is enough to answer «what is failing?». `counts` has the number of problems per status with the same filters,
whatever `status` you asked for.

**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`.
- `status` (string, optional, default `open`): Which problems to return. One of: `open`, `resolved`, `ignored`, `all`.
- `kind` (string, optional): `error` (an exception, in the browser or on the server), `failed_call` (a call that failed without an exception) or `timeout` (a request that never finished).
- `release` (string, optional): Only problems seen in this release version.
- `route` (string, optional): Only problems on this page or API route, as Sypnia normalizes it (`/orders/:id`).
- `q` (string, up to 120 characters, optional): Text to find in the sentence, the title, the slug or the file. Up to 120 characters.
- `since` (string, optional, default `30d`): Only problems seen after this moment.
- `until` (string, optional): End of the time range. An ISO 8601 timestamp or a relative value. Defaults to now.
- `sort` (string, optional, default `last_seen`): `last_seen` (newest activity first), `first_seen` (newest problem first), `people` or `occurrences` (most first, counted over the life of the problem).
- `limit` (integer, 1 to 200, optional, default `50`): Most items to return.
- `cursor` (string, optional): The `next_cursor` of the previous page. Keep every other parameter the same.

**Request:**

```bash
curl "https://api.sypnia.com/v1/problems?status=open" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"
```

**Response (200):**

```json
{
  "data": [
    {
      "id": "prb_8f3k2m9x4q7w",
      "slug": "pay-button-does-nothing",
      "fingerprint": "88a44b15205cb153",
      "kind": "failed_call",
      "origin": "server",
      "status": "open",
      "regressed": false,
      "title": "createPayment answered 400 in POST /api/checkout",
      "environment": "production",
      "route": "/checkout",
      "where": {
        "file": "src/checkout/checkout.tsx",
        "line": 142,
        "function": "confirmPayment"
      },
      "first_seen": "2026-03-12T09:12:04Z",
      "last_seen": "2026-03-12T10:31:47Z",
      "first_release": "4f2a91c",
      "last_release": "4f2a91c",
      "occurrences": 5,
      "people": 3,
      "sessions": 3,
      "resolved_at": null,
      "resolved_by": null,
      "resolved_in_release": null,
      "note": null,
      "analysis": {
        "status": "ready",
        "sentence": "3 people tried to pay today and could not. The Pay button does nothing since yesterday's change.",
        "who": "3 people. Two of them tried again and gave up.",
        "doing": "Paying for an order, at the last step of checkout.",
        "since": "Yesterday's change, deployed at 18:40. It worked before.",
        "cause": {
          "text": "Release 4f2a91c renamed the cart's total from cart.total to cart.totalCents. The checkout still reads cart.total, so the payment goes out without an amount and the API answers 400.",
          "evidence": [
            {
              "kind": "release_change",
              "ref": "4f2a91c:src/cart/cart.ts",
              "text": "The release renames `total` to `totalCents` in the Cart type."
            },
            {
              "kind": "stack_frame",
              "ref": "src/checkout/checkout.tsx:142",
              "text": "confirmPayment() still passes `cart.total` to createPayment()."
            },
            {
              "kind": "trace",
              "ref": "7c2e9a4b1d8f4e6a9b3c5d7e1f2a4b6c",
              "text": "POST /api/checkout answered 400 with the code `amount_required`."
            },
            {
              "kind": "timing",
              "ref": "4f2a91c",
              "text": "No failure of this kind before the release went live. All 5 failures are on it."
            }
          ]
        },
        "what_to_do": "Read cart.totalCents in confirmPayment(), and show the customer a message when a payment is rejected.",
        "confidence": "high",
        "generated_at": "2026-03-12T10:33:05Z",
        "provider": "openrouter",
        "model": "<model>",
        "runs": 3
      },
      "pull_request": null,
      "url": "https://app.sypnia.com/shop/problems/pay-button-does-nothing",
      "created_at": "2026-03-12T09:13:02Z"
    }
  ],
  "counts": {
    "open": 1,
    "resolved": 4,
    "ignored": 1
  },
  "next_cursor": null
}
```

## Get a problem

`GET /v1/problems/{problem}` \[Engine, Cloud]

The problem with its analysis. For everything a fix needs (stack, breadcrumbs, trace, release), ask for its context.

**Authentication:** API token (`read`)

**Path parameters:**

- `problem` (string, required): The problem's id (`prb_…`) or its slug, current or past.

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

**Request:**

```bash
curl "https://api.sypnia.com/v1/problems/pay-button-does-nothing" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"
```

**Response (200):**

```json
{
  "id": "prb_8f3k2m9x4q7w",
  "slug": "pay-button-does-nothing",
  "fingerprint": "88a44b15205cb153",
  "kind": "failed_call",
  "origin": "server",
  "status": "open",
  "regressed": false,
  "title": "createPayment answered 400 in POST /api/checkout",
  "environment": "production",
  "route": "/checkout",
  "where": {
    "file": "src/checkout/checkout.tsx",
    "line": 142,
    "function": "confirmPayment"
  },
  "first_seen": "2026-03-12T09:12:04Z",
  "last_seen": "2026-03-12T10:31:47Z",
  "first_release": "4f2a91c",
  "last_release": "4f2a91c",
  "occurrences": 5,
  "people": 3,
  "sessions": 3,
  "resolved_at": null,
  "resolved_by": null,
  "resolved_in_release": null,
  "note": null,
  "analysis": {
    "status": "ready",
    "sentence": "3 people tried to pay today and could not. The Pay button does nothing since yesterday's change.",
    "who": "3 people. Two of them tried again and gave up.",
    "doing": "Paying for an order, at the last step of checkout.",
    "since": "Yesterday's change, deployed at 18:40. It worked before.",
    "cause": {
      "text": "Release 4f2a91c renamed the cart's total from cart.total to cart.totalCents. The checkout still reads cart.total, so the payment goes out without an amount and the API answers 400.",
      "evidence": [
        {
          "kind": "release_change",
          "ref": "4f2a91c:src/cart/cart.ts",
          "text": "The release renames `total` to `totalCents` in the Cart type."
        },
        {
          "kind": "stack_frame",
          "ref": "src/checkout/checkout.tsx:142",
          "text": "confirmPayment() still passes `cart.total` to createPayment()."
        },
        {
          "kind": "trace",
          "ref": "7c2e9a4b1d8f4e6a9b3c5d7e1f2a4b6c",
          "text": "POST /api/checkout answered 400 with the code `amount_required`."
        },
        {
          "kind": "timing",
          "ref": "4f2a91c",
          "text": "No failure of this kind before the release went live. All 5 failures are on it."
        }
      ]
    },
    "what_to_do": "Read cart.totalCents in confirmPayment(), and show the customer a message when a payment is rejected.",
    "confidence": "high",
    "generated_at": "2026-03-12T10:33:05Z",
    "provider": "openrouter",
    "model": "<model>",
    "runs": 3
  },
  "pull_request": null,
  "url": "https://app.sypnia.com/shop/problems/pay-button-does-nothing",
  "created_at": "2026-03-12T09:13:02Z"
}
```

**Errors:**

- `404` `not_found`: No problem has this id or slug in the project.

## Get a problem's context

`GET /v1/problems/{problem}/context` \[Engine, Cloud]

Everything a person or a coding agent needs to fix the problem, in one answer: the problem and its analysis,
the stack with your own source lines, what the person did before the failure, the trace of the failing
request, the release and what changed in it, who was affected, and sessions to watch.

The stack, breadcrumbs and trace come from one occurrence, named in `sample`: the latest one that has a
trace and a replay, or else the latest. Pass `session` to build the context from another session.

A part that does not exist is `null` and listed in `missing`, with the reason, so a caller never has to guess
why something is absent: `source_maps_not_uploaded`, `no_trace`, `release_unknown`, `expired`.

This is the same data the agent reads, before redaction. It is what the MCP tool `problem` returns.

**Authentication:** API token (`read`)

**Path parameters:**

- `problem` (string, required): The problem's id (`prb_…`) or its slug, current or past.

**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`.
- `session` (string, optional): Build the stack, breadcrumbs and trace from this session's occurrence instead of the default one.
- `breadcrumbs` (integer, 0 to 100, optional, default `30`): How many events before the failure to return.
- `source_lines` (integer, 0 to 20, optional, default `5`): Lines of source to return around each frame of your own code, on each side.

**Request:**

```bash
curl "https://api.sypnia.com/v1/problems/pay-button-does-nothing/context" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"
```

**Response (200):**

```json
{
  "problem": {
    "id": "prb_8f3k2m9x4q7w",
    "slug": "pay-button-does-nothing",
    "…": "the whole problem object, as in «Get a problem»"
  },
  "sample": {
    "session_id": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
    "at": "2026-03-12T10:31:47Z",
    "trace_id": "7c2e9a4b1d8f4e6a9b3c5d7e1f2a4b6c",
    "release": "4f2a91c",
    "browser": "Chrome 134",
    "os": "macOS",
    "device": "desktop"
  },
  "stack": {
    "origin": "browser",
    "error": {
      "name": "ApiError",
      "message": "POST /api/checkout failed with 400 (amount_required)"
    },
    "symbolicated": true,
    "frames": [
      {
        "function": "createPayment",
        "file": "src/lib/api.ts",
        "line": 27,
        "column": 11,
        "in_app": true,
        "source": {
          "start_line": 25,
          "lines": [
            "  const res = await fetch('/api/checkout', { method: 'POST', body: JSON.stringify(input) });",
            "  if (!res.ok) {",
            "    throw new ApiError('POST', '/api/checkout', res.status, await errorCode(res));",
            "  }",
            "  return res.json();"
          ]
        }
      },
      {
        "function": "confirmPayment",
        "file": "src/checkout/checkout.tsx",
        "line": 142,
        "column": 21,
        "in_app": true,
        "source": {
          "start_line": 140,
          "lines": [
            "async function confirmPayment(cart: Cart) {",
            "  setPaying(true);",
            "  const payment = await createPayment({ amount: cart.total, currency: cart.currency });",
            "  router.push(`/orders/${payment.orderId}`);",
            "}"
          ]
        }
      },
      {
        "function": "onClick",
        "file": "src/checkout/pay-button.tsx",
        "line": 18,
        "column": 5,
        "in_app": true,
        "source": {
          "start_line": 17,
          "lines": [
            "  <button type=\"submit\" disabled={paying} onClick={() => confirmPayment(cart)}>",
            "    Pay {formatMoney(cart)}",
            "  </button>"
          ]
        }
      }
    ],
    "raw": "ApiError: POST /api/checkout failed with 400 (amount_required)\n    at createPayment (https://shop.example.com/assets/checkout-3f9c.js:1:48211)\n    at async confirmPayment (https://shop.example.com/assets/checkout-3f9c.js:1:51377)\n    at async onClick (https://shop.example.com/assets/checkout-3f9c.js:1:52904)"
  },
  "breadcrumbs": [
    {
      "at": "2026-03-12T10:31:28.412Z",
      "offset_ms": 12412,
      "type": "page_view",
      "route": "/checkout",
      "text": "Opened /checkout (from /cart)",
      "data": {
        "navigation": "push",
        "from": "/cart"
      },
      "trace_id": null,
      "problem_id": null
    },
    {
      "at": "2026-03-12T10:31:43.090Z",
      "offset_ms": 27090,
      "type": "click",
      "route": "/checkout",
      "text": "Clicked button «Pay $64.00» in «Your order»",
      "data": {
        "selector": "#pay-button",
        "role": "button",
        "label": "Pay $64.00",
        "context": "Your order",
        "href": null
      },
      "trace_id": null,
      "problem_id": null
    },
    {
      "at": "2026-03-12T10:31:45.310Z",
      "offset_ms": 29310,
      "type": "rage_click",
      "route": "/checkout",
      "text": "Clicked button «Pay $64.00» 4 more times",
      "data": {
        "selector": "#pay-button",
        "role": "button",
        "label": "Pay $64.00",
        "context": "Your order",
        "count": 4
      },
      "trace_id": null,
      "problem_id": null
    },
    {
      "at": "2026-03-12T10:31:47.000Z",
      "offset_ms": 31000,
      "type": "request",
      "route": "/checkout",
      "text": "POST /api/checkout answered 400 amount_required after 3,870 ms",
      "data": {
        "method": "POST",
        "path": "/api/checkout",
        "status": 400,
        "duration_ms": 3870,
        "code": "amount_required",
        "message": "amount is required"
      },
      "trace_id": "7c2e9a4b1d8f4e6a9b3c5d7e1f2a4b6c",
      "problem_id": null
    }
  ],
  "trace": {
    "id": "7c2e9a4b1d8f4e6a9b3c5d7e1f2a4b6c",
    "…": "the whole trace with its spans, as in «Get a trace»"
  },
  "release": {
    "version": "4f2a91c",
    "…": "the whole release with its changes, as in «Get a release»"
  },
  "impact": {
    "people": 3,
    "sessions": 3,
    "occurrences": 5,
    "people_who_retried": 2,
    "by_release": {
      "4f2a91c": 5
    },
    "by_browser": {
      "Chrome 134": 3,
      "Safari 18": 2
    },
    "by_device": {
      "desktop": 3,
      "mobile": 2
    },
    "last_success_before": "2026-03-11T17:52:30Z"
  },
  "sessions": [
    {
      "id": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
      "started_at": "2026-03-12T10:31:16Z",
      "duration_ms": 42000,
      "person": {
        "id": "u_1042",
        "name": "Ada Park",
        "email": "ada@example.com"
      },
      "has_replay": true,
      "occurrences": 1,
      "first_occurrence_at": "2026-03-12T10:31:47Z",
      "url": "https://app.sypnia.com/shop/sessions/8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0?at=31000"
    }
  ],
  "missing": [],
  "links": {
    "prompt": "/v1/problems/prb_8f3k2m9x4q7w/prompt",
    "problem": "https://app.sypnia.com/shop/problems/pay-button-does-nothing"
  }
}
```

**Errors:**

- `404` `not_found`: No problem has this id or slug, or `session` is not a session of this problem.

## Get the ready prompt

`GET /v1/problems/{problem}/prompt` \[Engine, Cloud]

The prompt to paste into a coding agent. It always exists. With an analysis it says what happens, where, why,
what to do and how to check. Without one (no AI provider, or not enough evidence) it carries the evidence and
asks the coding agent to find the cause. Its structure is fixed and documented in
[The prompt](https://docs.sypnia.com/agent/the-prompt). It is at most 12,000 characters.

Ask for `format=text`, or send `Accept: text/plain`, to get only the prompt as plain text.

**Authentication:** API token (`read`)

**Path parameters:**

- `problem` (string, required): The problem's id (`prb_…`) or its slug, current or past.

**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`.
- `format` (string, optional, default `json`): `json` wraps the prompt with its facts. `text` returns the prompt alone, as `text/plain`.

**Request:**

```bash
curl "https://api.sypnia.com/v1/problems/pay-button-does-nothing/prompt?format=text" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"
```

**Response (200):**

```json
{
  "problem_id": "prb_8f3k2m9x4q7w",
  "slug": "pay-button-does-nothing",
  "analysis_status": "ready",
  "generated_at": "2026-03-12T10:33:05Z",
  "chars": 2648,
  "prompt": "Fix a production bug reported by Sypnia.\n\nWhat happens: clicking Pay does nothing. 3 people hit it today (2026-03-12),\n  since release 4f2a91c (deployed 2026-03-11 18:40 UTC).\nWhere: src/checkout/checkout.tsx:142, confirmPayment()\nWhy: that release renamed cart.total to cart.totalCents, but\n  checkout.tsx still reads cart.total. The payment goes out\n  with amount undefined and the API answers 400.\n  Confidence: high.\nDo: read cart.totalCents in confirmPayment(), and show the\n  customer a message when a payment is rejected.\nCheck: session 8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0 shows the clicks.\n  Add a test that fails when the amount is missing.\n\n… (the evidence and the rules follow; the full text is on the page «The prompt»)"
}
```

**Errors:**

- `404` `not_found`: No problem has this id or slug in the project.

## Get a problem's timeline

`GET /v1/problems/{problem}/timeline` \[Engine, Cloud]

How often the problem happened over time, and the moments that explain the curve: when it was first seen,
which releases went live, when it was analysed, resolved or reopened. Buckets with nothing in them are
returned with zeros, so the series has no holes.

**Authentication:** API token (`read`)

**Path parameters:**

- `problem` (string, required): The problem's id (`prb_…`) or its slug, current or past.

**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`.
- `since` (string, optional, default `14d`): Start of the series.
- `until` (string, optional): End of the time range. An ISO 8601 timestamp or a relative value. Defaults to now.
- `interval` (string, optional, default `day`): Size of each bucket. `hour` is allowed for ranges up to 7 days. Days are cut in the project's time zone.

**Request:**

```bash
curl "https://api.sypnia.com/v1/problems/pay-button-does-nothing/timeline?since=2d&interval=day" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"
```

**Response (200):**

```json
{
  "interval": "day",
  "timezone": "UTC",
  "buckets": [
    {
      "start": "2026-03-11T00:00:00Z",
      "occurrences": 0,
      "people": 0,
      "sessions": 0
    },
    {
      "start": "2026-03-12T00:00:00Z",
      "occurrences": 5,
      "people": 3,
      "sessions": 3
    }
  ],
  "markers": [
    {
      "at": "2026-03-11T18:40:00Z",
      "type": "release",
      "release": "4f2a91c"
    },
    {
      "at": "2026-03-12T09:12:04Z",
      "type": "first_seen"
    },
    {
      "at": "2026-03-12T09:13:40Z",
      "type": "analysis",
      "confidence": "medium"
    },
    {
      "at": "2026-03-12T10:33:05Z",
      "type": "analysis",
      "confidence": "high"
    }
  ]
}
```

**Errors:**

- `400` `invalid_request`: `interval=hour` with a range longer than 7 days.
- `404` `not_found`: No problem has this id or slug in the project.

## List the sessions a problem affected

`GET /v1/problems/{problem}/sessions` \[Engine, Cloud]

The sessions in which the problem happened, latest first. Each is a session object with two more fields:
`occurrences`, how many times it happened in that session, and `first_occurrence_at`, the moment to jump to
in the replay. The engine keeps up to 200 session ids per problem and day; `people` and `sessions` on the
problem are still exact.

**Authentication:** API token (`read`)

**Path parameters:**

- `problem` (string, required): The problem's id (`prb_…`) or its slug, current or past.

**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`.
- `since` (string, optional, default `30d`): Only sessions after this moment.
- `until` (string, optional): End of the time range. An ISO 8601 timestamp or a relative value. Defaults to now.
- `has_replay` (boolean, optional): `true` returns only sessions that have a replay.
- `limit` (integer, 1 to 200, optional, default `50`): Most items to return.
- `cursor` (string, optional): The `next_cursor` of the previous page. Keep every other parameter the same.

**Request:**

```bash
curl "https://api.sypnia.com/v1/problems/pay-button-does-nothing/sessions" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"
```

**Response (200):**

```json
{
  "data": [
    {
      "id": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
      "started_at": "2026-03-12T10:31:16Z",
      "ended_at": "2026-03-12T10:31:58Z",
      "duration_ms": 42000,
      "person": {
        "id": "u_1042",
        "name": "Ada Park",
        "email": "ada@example.com"
      },
      "account": {
        "id": "acc_77",
        "name": "Corner Café"
      },
      "environment": "production",
      "release": "4f2a91c",
      "device": "desktop",
      "browser": "Chrome 134",
      "os": "macOS",
      "locale": "en-US",
      "entry_route": "/cart",
      "routes": [
        "/cart",
        "/checkout"
      ],
      "page_views": 2,
      "clicks": 7,
      "rage_clicks": 1,
      "dead_clicks": 0,
      "errors": 1,
      "requests": 6,
      "failed_requests": 1,
      "trouble": true,
      "has_replay": true,
      "url": "https://app.sypnia.com/shop/sessions/8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
      "occurrences": 1,
      "first_occurrence_at": "2026-03-12T10:31:47Z"
    },
    {
      "id": "2b7d9e4f1a6c4830b5d2f7e9c1a3b5d7",
      "started_at": "2026-03-12T09:47:40Z",
      "ended_at": "2026-03-12T09:49:02Z",
      "duration_ms": 82000,
      "person": {
        "id": "u_0977",
        "name": null,
        "email": null
      },
      "account": null,
      "environment": "production",
      "release": "4f2a91c",
      "device": "mobile",
      "browser": "Safari 18",
      "os": "iOS",
      "locale": "en-US",
      "entry_route": "/checkout",
      "routes": [
        "/checkout"
      ],
      "page_views": 1,
      "clicks": 4,
      "rage_clicks": 0,
      "dead_clicks": 0,
      "errors": 2,
      "requests": 5,
      "failed_requests": 2,
      "trouble": true,
      "has_replay": true,
      "url": "https://app.sypnia.com/shop/sessions/2b7d9e4f1a6c4830b5d2f7e9c1a3b5d7",
      "occurrences": 2,
      "first_occurrence_at": "2026-03-12T09:48:11Z"
    },
    {
      "id": "c4e1a8f3d7b24c69a0e5d3b1f9c7a5e3",
      "started_at": "2026-03-12T09:11:26Z",
      "ended_at": "2026-03-12T09:13:15Z",
      "duration_ms": 109000,
      "person": null,
      "account": null,
      "environment": "production",
      "release": "4f2a91c",
      "device": "desktop",
      "browser": "Chrome 134",
      "os": "Windows",
      "locale": "en-GB",
      "entry_route": "/",
      "routes": [
        "/",
        "/products/:id",
        "/cart",
        "/checkout"
      ],
      "page_views": 4,
      "clicks": 11,
      "rage_clicks": 0,
      "dead_clicks": 0,
      "errors": 2,
      "requests": 14,
      "failed_requests": 2,
      "trouble": true,
      "has_replay": true,
      "url": "https://app.sypnia.com/shop/sessions/c4e1a8f3d7b24c69a0e5d3b1f9c7a5e3",
      "occurrences": 2,
      "first_occurrence_at": "2026-03-12T09:12:04Z"
    }
  ],
  "next_cursor": null
}
```

**Errors:**

- `404` `not_found`: No problem has this id or slug in the project.

## Resolve a problem

`POST /v1/problems/{problem}/resolve` \[Engine, Cloud]

Marks the problem as fixed. If the failure happens again the problem reopens by itself, `regressed` becomes
`true` and an alert is created, so resolving too early is safe.

Pass `release` when you know which release carries the fix. Then failures from older releases, such as a
browser tab that was open before the deploy, do not reopen the problem; only a failure in that release or a
later one does.

Resolving a resolved problem changes nothing and answers `200`.

A `read` token is enough: resolving is a reversible mark, recorded with the token's name in `resolved_by`.

**Authentication:** API token (`read`)

**Path parameters:**

- `problem` (string, required): The problem's id (`prb_…`) or its slug, current or past.

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

**Body:**

- `release` (string, up to 40 characters, optional): The version of the release that carries the fix. Failures from releases older than it will not reopen the problem.
- `note` (string, up to 500 characters, optional): Why, for whoever reads the problem later.

**Request:**

```bash
curl -X POST "https://api.sypnia.com/v1/problems/pay-button-does-nothing/resolve" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"release": "5b3c8d2", "note": "Fixed in pull request 128."}'
```

**Response (200):**

```json
{
  "id": "prb_8f3k2m9x4q7w",
  "slug": "pay-button-does-nothing",
  "fingerprint": "88a44b15205cb153",
  "kind": "failed_call",
  "origin": "server",
  "status": "resolved",
  "regressed": false,
  "title": "createPayment answered 400 in POST /api/checkout",
  "environment": "production",
  "route": "/checkout",
  "where": {
    "file": "src/checkout/checkout.tsx",
    "line": 142,
    "function": "confirmPayment"
  },
  "first_seen": "2026-03-12T09:12:04Z",
  "last_seen": "2026-03-12T10:31:47Z",
  "first_release": "4f2a91c",
  "last_release": "4f2a91c",
  "occurrences": 5,
  "people": 3,
  "sessions": 3,
  "resolved_at": "2026-03-12T11:20:44Z",
  "resolved_by": "token:Cursor",
  "resolved_in_release": "5b3c8d2",
  "note": "Fixed in pull request 128.",
  "analysis": {
    "status": "ready",
    "sentence": "3 people tried to pay today and could not. The Pay button does nothing since yesterday's change.",
    "who": "3 people. Two of them tried again and gave up.",
    "doing": "Paying for an order, at the last step of checkout.",
    "since": "Yesterday's change, deployed at 18:40. It worked before.",
    "cause": {
      "text": "Release 4f2a91c renamed the cart's total from cart.total to cart.totalCents. The checkout still reads cart.total, so the payment goes out without an amount and the API answers 400.",
      "evidence": [
        {
          "kind": "release_change",
          "ref": "4f2a91c:src/cart/cart.ts",
          "text": "The release renames `total` to `totalCents` in the Cart type."
        },
        {
          "kind": "stack_frame",
          "ref": "src/checkout/checkout.tsx:142",
          "text": "confirmPayment() still passes `cart.total` to createPayment()."
        },
        {
          "kind": "trace",
          "ref": "7c2e9a4b1d8f4e6a9b3c5d7e1f2a4b6c",
          "text": "POST /api/checkout answered 400 with the code `amount_required`."
        },
        {
          "kind": "timing",
          "ref": "4f2a91c",
          "text": "No failure of this kind before the release went live. All 5 failures are on it."
        }
      ]
    },
    "what_to_do": "Read cart.totalCents in confirmPayment(), and show the customer a message when a payment is rejected.",
    "confidence": "high",
    "generated_at": "2026-03-12T10:33:05Z",
    "provider": "openrouter",
    "model": "<model>",
    "runs": 3
  },
  "pull_request": null,
  "url": "https://app.sypnia.com/shop/problems/pay-button-does-nothing",
  "created_at": "2026-03-12T09:13:02Z"
}
```

**Errors:**

- `404` `not_found`: No problem has this id or slug in the project.
- `409` `conflict`: The problem is `ignored`. Reopen it first.

## Reopen a problem

`POST /v1/problems/{problem}/reopen` \[Engine, Cloud]

Sets a resolved or ignored problem back to `open`. Reopening an open problem changes nothing and answers `200`.

**Authentication:** API token (`read`)

**Path parameters:**

- `problem` (string, required): The problem's id (`prb_…`) or its slug, current or past.

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

**Body:**

- `note` (string, up to 500 characters, optional): Why, for whoever reads the problem later.

**Request:**

```bash
curl -X POST "https://api.sypnia.com/v1/problems/pay-button-does-nothing/reopen" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"
```

**Response (200):**

```json
{
  "id": "prb_8f3k2m9x4q7w",
  "slug": "pay-button-does-nothing",
  "fingerprint": "88a44b15205cb153",
  "kind": "failed_call",
  "origin": "server",
  "status": "open",
  "regressed": false,
  "title": "createPayment answered 400 in POST /api/checkout",
  "environment": "production",
  "route": "/checkout",
  "where": {
    "file": "src/checkout/checkout.tsx",
    "line": 142,
    "function": "confirmPayment"
  },
  "first_seen": "2026-03-12T09:12:04Z",
  "last_seen": "2026-03-12T10:31:47Z",
  "first_release": "4f2a91c",
  "last_release": "4f2a91c",
  "occurrences": 5,
  "people": 3,
  "sessions": 3,
  "resolved_at": null,
  "resolved_by": null,
  "resolved_in_release": null,
  "note": null,
  "analysis": {
    "status": "ready",
    "sentence": "3 people tried to pay today and could not. The Pay button does nothing since yesterday's change.",
    "who": "3 people. Two of them tried again and gave up.",
    "doing": "Paying for an order, at the last step of checkout.",
    "since": "Yesterday's change, deployed at 18:40. It worked before.",
    "cause": {
      "text": "Release 4f2a91c renamed the cart's total from cart.total to cart.totalCents. The checkout still reads cart.total, so the payment goes out without an amount and the API answers 400.",
      "evidence": [
        {
          "kind": "release_change",
          "ref": "4f2a91c:src/cart/cart.ts",
          "text": "The release renames `total` to `totalCents` in the Cart type."
        },
        {
          "kind": "stack_frame",
          "ref": "src/checkout/checkout.tsx:142",
          "text": "confirmPayment() still passes `cart.total` to createPayment()."
        },
        {
          "kind": "trace",
          "ref": "7c2e9a4b1d8f4e6a9b3c5d7e1f2a4b6c",
          "text": "POST /api/checkout answered 400 with the code `amount_required`."
        },
        {
          "kind": "timing",
          "ref": "4f2a91c",
          "text": "No failure of this kind before the release went live. All 5 failures are on it."
        }
      ]
    },
    "what_to_do": "Read cart.totalCents in confirmPayment(), and show the customer a message when a payment is rejected.",
    "confidence": "high",
    "generated_at": "2026-03-12T10:33:05Z",
    "provider": "openrouter",
    "model": "<model>",
    "runs": 3
  },
  "pull_request": null,
  "url": "https://app.sypnia.com/shop/problems/pay-button-does-nothing",
  "created_at": "2026-03-12T09:13:02Z"
}
```

**Errors:**

- `404` `not_found`: No problem has this id or slug in the project.

## Ignore a problem

`POST /v1/problems/{problem}/ignore` \[Engine, Cloud]

Marks the problem as known and accepted. An ignored problem keeps counting, never alerts, is never analysed
again and never reopens by itself. Because it silences alerts, it needs the `admin` scope.

**Authentication:** API token (`admin`)

**Path parameters:**

- `problem` (string, required): The problem's id (`prb_…`) or its slug, current or past.

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

**Body:**

- `note` (string, up to 500 characters, optional): Why, for whoever reads the problem later.

**Request:**

```bash
curl -X POST "https://api.sypnia.com/v1/problems/prb_2c7n5v1b9m3k/ignore" \
  -H "Authorization: Bearer $SYPNIA_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"note": "Open tabs after a deploy. Accepted for now."}'
```

**Response (200):**

```json
{
  "id": "prb_2c7n5v1b9m3k",
  "slug": "search-page-part-does-not-load",
  "fingerprint": "51d0a9c3e7f2b846",
  "kind": "error",
  "origin": "browser",
  "status": "ignored",
  "regressed": false,
  "title": "TypeError: Failed to fetch dynamically imported module",
  "environment": "production",
  "route": "/search",
  "where": null,
  "first_seen": "2026-03-02T14:20:11Z",
  "last_seen": "2026-03-11T18:44:30Z",
  "first_release": "2e6b0f4",
  "last_release": "9c1e7b2",
  "occurrences": 212,
  "people": 41,
  "sessions": 57,
  "resolved_at": null,
  "resolved_by": null,
  "resolved_in_release": null,
  "note": "Open tabs after a deploy. Accepted for now.",
  "analysis": {
    "status": "not_enough_evidence",
    "sentence": "41 people could not load part of the search page. It happens in the minutes after a deploy.",
    "who": "41 people who had the page open while a new release went live.",
    "doing": "Browsing search results.",
    "since": "First seen on 2 March. It comes back with every release.",
    "cause": null,
    "what_to_do": null,
    "confidence": null,
    "generated_at": "2026-03-02T14:21:02Z",
    "provider": "openrouter",
    "model": "<model>",
    "runs": 2
  },
  "pull_request": null,
  "url": "https://app.sypnia.com/shop/problems/search-page-part-does-not-load",
  "created_at": "2026-03-02T14:20:58Z"
}
```

**Errors:**

- `403` `forbidden`: The token does not have the `admin` scope.
- `404` `not_found`: No problem has this id or slug in the project.

## Analyse a problem again

`POST /v1/problems/{problem}/analyze` \[Engine, Cloud]

Asks the agent to analyse the problem now, with the newest evidence. The agent already runs by itself when a
problem is new, when it grows and when it comes back; use this after you uploaded source maps or registered
the release, which give it more to read. The answer comes at once with `analysis.status` set to `pending`;
read the problem again, or listen for the `problem.analyzed` webhook, to get the result.

It counts against the daily limit of analyses.

**Authentication:** API token (`admin`)

**Path parameters:**

- `problem` (string, required): The problem's id (`prb_…`) or its slug, current or past.

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

**Headers:**

- `Idempotency-Key` (string, up to 255 characters, optional): A value of your own, 1 to 255 characters, that makes the call safe to repeat. See [idempotency](https://docs.sypnia.com/api/errors-limits-pagination#idempotency).

**Request:**

```bash
curl -X POST "https://api.sypnia.com/v1/problems/pay-button-does-nothing/analyze" \
  -H "Authorization: Bearer $SYPNIA_ADMIN_TOKEN"
```

**Response (202):**

```json
{
  "problem_id": "prb_8f3k2m9x4q7w",
  "analysis": {
    "status": "pending"
  },
  "analyses_left_today": 46
}
```

**Errors:**

- `404` `not_found`: No problem has this id or slug in the project.
- `409` `ai_not_configured`: The engine has no AI provider (`SYPNIA_AI_PROVIDER` is `none`), or the project switched the agent off.
- `409` `conflict`: The problem is `ignored`, or an analysis of it is already running.
- `429` `analysis_limit_reached`: The project used its analyses for today. `Retry-After` says when the count resets.

## Open a pull request with the fix

`POST /v1/problems/{problem}/pull-request` \[Cloud]

Asks the Sypnia GitHub App to write the fix and open a pull request. It is the «Open pull request» button of
the app. The answer comes at once; the pull request appears on the problem (`pull_request`) within a few
minutes, and a `problem.pull_request_opened` webhook is sent.

Sypnia never merges. See [Pull requests](https://docs.sypnia.com/agent/pull-requests) for what the pull request contains and
what the GitHub App may do.

A self-hosted engine does not have this endpoint: it answers `404 cloud_only`. Use the prompt or the MCP
server with your own coding agent.

**Authentication:** API token (`admin`)

**Path parameters:**

- `problem` (string, required): The problem's id (`prb_…`) or its slug, current or past.

**Headers:**

- `Idempotency-Key` (string, up to 255 characters, optional): A value of your own, 1 to 255 characters, that makes the call safe to repeat. See [idempotency](https://docs.sypnia.com/api/errors-limits-pagination#idempotency).

**Request:**

```bash
curl -X POST "https://api.sypnia.com/v1/problems/pay-button-does-nothing/pull-request" \
  -H "Authorization: Bearer $SYPNIA_ADMIN_TOKEN"
```

**Response (202):**

```json
{
  "problem_id": "prb_8f3k2m9x4q7w",
  "pull_request": {
    "state": "queued",
    "branch": "sypnia/pay-button-does-nothing",
    "repository": "acme/shop",
    "number": null,
    "url": null,
    "opened_at": null
  },
  "fixes_left_this_month": 44
}
```

**Errors:**

- `404` `cloud_only`: The request went to a self-hosted engine.
- `409` `github_not_connected`: The project has no repository connected through the Sypnia GitHub App.
- `409` `not_enough_evidence`: The analysis is missing, or its confidence is `low` or it found no cause. Sypnia does not write a fix it cannot justify.
- `409` `pull_request_exists`: The problem already has an open pull request. Its URL is in the error's `message` and in the problem's `pull_request`.
- `429` `fixes_limit_reached`: The organization used this month's pull requests. See [Limits](https://docs.sypnia.com/agent/limits).

The errors every endpoint can answer (`401`, `403`, `429`, `500`, `503`) are on [Errors, limits, pagination](https://docs.sypnia.com/api/errors-limits-pagination).
