Docs

Problems

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

Applies to EngineCloud At launch

View as Markdown
On this page
  1. Status
  2. The problem object
  3. The analysis object
  4. List problems
  5. Get a problem
  6. Get a problem’s context
  7. Get the ready prompt
  8. Get a problem’s timeline
  9. List the sessions a problem affected
  10. Resolve a problem
  11. Reopen a problem
  12. Ignore a problem
  13. Analyse a problem again
  14. Open a pull request with the fix

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

StatusMeaningHow it changes
openIt is happening, or nobody has said otherwiseThe starting status
resolvedSomeone fixed itPOST …/resolve. If the failure comes back, the problem reopens by itself and regressed becomes true
ignoredKnown and accepted. It never alerts and never reopensPOST …/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.

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

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 EngineCloud

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

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

    Default: production

  • status
    string optional

    Which problems to return. One of: open, resolved, ignored, all.

    Default: open

  • 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

    Only problems seen after this moment.

    Default: 30d

  • until
    string optional

    End of the time range. An ISO 8601 timestamp or a relative value. Defaults to now.

  • sort
    string optional

    last_seen (newest activity first), first_seen (newest problem first), people or occurrences (most first, counted over the life of the problem).

    Default: last_seen

  • limit
    integer, 1 to 200 optional

    Most items to return.

    Default: 50

  • cursor
    string optional

    The next_cursor of the previous page. Keep every other parameter the same.

Request

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

Response200

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} EngineCloud

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

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

Response200

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

  • 404not_found

    No problem has this id or slug in the project.

Get a problem’s context

GET /v1/problems/{problem}/context EngineCloud

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

    How many events before the failure to return.

    Default: 30

  • source_lines
    integer, 0 to 20 optional

    Lines of source to return around each frame of your own code, on each side.

    Default: 5

Request

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

Response200

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

  • 404not_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 EngineCloud

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

    json wraps the prompt with its facts. text returns the prompt alone, as text/plain.

    Default: json

Request

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

Response200

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

  • 404not_found

    No problem has this id or slug in the project.

Get a problem’s timeline

GET /v1/problems/{problem}/timeline EngineCloud

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

    Start of the series.

    Default: 14d

  • until
    string optional

    End of the time range. An ISO 8601 timestamp or a relative value. Defaults to now.

  • interval
    string optional

    Size of each bucket. hour is allowed for ranges up to 7 days. Days are cut in the project’s time zone.

    Default: day

Request

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

Response200

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

  • 400invalid_request

    interval=hour with a range longer than 7 days.

  • 404not_found

    No problem has this id or slug in the project.

List the sessions a problem affected

GET /v1/problems/{problem}/sessions EngineCloud

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

    Only sessions after this moment.

    Default: 30d

  • 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

    Most items to return.

    Default: 50

  • cursor
    string optional

    The next_cursor of the previous page. Keep every other parameter the same.

Request

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

Response200

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

  • 404not_found

    No problem has this id or slug in the project.

Resolve a problem

POST /v1/problems/{problem}/resolve EngineCloud

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

Terminal
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."}'

Response200

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

  • 404not_found

    No problem has this id or slug in the project.

  • 409conflict

    The problem is ignored. Reopen it first.

Reopen a problem

POST /v1/problems/{problem}/reopen EngineCloud

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

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

Response200

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

  • 404not_found

    No problem has this id or slug in the project.

Ignore a problem

POST /v1/problems/{problem}/ignore EngineCloud

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

Terminal
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."}'

Response200

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

  • 403forbidden

    The token does not have the admin scope.

  • 404not_found

    No problem has this id or slug in the project.

Analyse a problem again

POST /v1/problems/{problem}/analyze EngineCloud

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.

Request

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

Response202

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

Errors

  • 404not_found

    No problem has this id or slug in the project.

  • 409ai_not_configured

    The engine has no AI provider (SYPNIA_AI_PROVIDER is none), or the project switched the agent off.

  • 409conflict

    The problem is ignored, or an analysis of it is already running.

  • 429analysis_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 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.

Request

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

Response202

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

  • 404cloud_only

    The request went to a self-hosted engine.

  • 409github_not_connected

    The project has no repository connected through the Sypnia GitHub App.

  • 409not_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.

  • 409pull_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.

  • 429fixes_limit_reached

    The organization used this month’s pull requests. See Limits.

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