API Reference

FixNoty API v1 is a versioned, read-only HTTP interface for exporting every report that belongs to a single project. It is designed for scripts, CI, internal tools, and later automations — including an AI agent that needs the same solving context a human sees in the dashboard.

The API never changes status, never writes comments, never deletes objects, and never returns raw storage paths or secret material. Media is delivered as time-bounded signed URLs. Session replay is delivered either as rrweb event chunks or as a 24-hour signed link to the same interactive player used in the dashboard Replay tab — not as a newly encoded MP4.

• Protocol: HTTPS JSON. Request bodies are not used (all methods are GET).
• Prefix: /api/v1. Locale prefixes such as /en or /it are for the website only; they are not part of the API path.
• Scope: one project per key. Cross-project IDs return 404 with code not_found.
• Compatibility: status, priority, and category enums are the Italian database strings (for example aperto). Do not translate them in clients.

Production host: https://www.fixnoty.com. Replace with your deployment origin in development. Concatenate the prefix without a trailing slash:

https://www.fixnoty.com/api/v1/feedback

Breaking changes ship under a new prefix (/api/v2). Additive JSON fields may appear in v1 without a version bump; clients must ignore unknown keys. There is no OpenAPI document in v1.

Authenticate with a project API key. The key is scoped to exactly one project and grants read access only. It authenticates the project, not a user: anyone who holds the secret (a script, a collaborator, an integration) can read every report in that project.

Send the secret with exactly one of these headers:

Authorization: Bearer fn_live_…
X-Api-Key: fn_live_…

If both are present, Authorization: Bearer wins. Query-string keys, cookies, and request bodies are ignored.

Failed responses use a stable JSON body. code is always English and is the field you should switch on. error is a human message and may be localized from Accept-Language (it or fallback en).

{
  "error": "Invalid or revoked API key.",
  "code": "invalid_api_key"
}

A malformed replay-player token, an expired token, or a token whose API key was revoked is not a v1 error: the watch page and its event stream respond with 404 or 410 and are not part of the versioned contract.

Sliding 60-second windows, counted in process memory per server instance (MVP; not a global Redis quota). Both limits apply:

• 60 requests / minute / client IP, evaluated before the key is parsed. Unauthenticated callers still consume this budget.
• 120 requests / minute / authenticated key, evaluated after a successful key lookup.

Exceeding either limit returns 429 with code rate_limited and a Retry-After header (seconds, minimum 1). API access is included with Agency, not sold as a separate plan.

Every v1 JSON response includes:

Cache-Control: private, no-store

Signed media URLs and player links must not be cached by CDNs or shared HTTP caches. Clients may keep a response in local memory until the enclosed expires_at and must call GET /feedback/:id/assets (or /replay) to mint a fresh URL.

Secrets are never written to application logs. Do not log Authorization, X-Api-Key, player tokens, or signed URL query strings.

GET /feedback uses keyset pagination on (updated_at DESC, id DESC). It does not use SQL OFFSET.

• Default page size 50; maximum 100. Values above the maximum are clamped, not rejected.
• When another page exists, has_more is true and next_cursor is an opaque base64url blob. Pass it back as cursor.
• A malformed cursor yields 400 invalid_request. Do not invent cursors; they are not a public query language.

Binary objects are never inlined in JSON and the API never returns a project zip. Each file is an object:

{
  "url": "https://…/object/sign/…?token=…",
  "expires_in": 1800,
  "expires_at": "2026-10-02T10:30:00.000Z"
}

GET the url directly. After expiry the object store rejects the token; call assets or replay again. Attachment rows also include id, file_name, mime_type, file_size, and created_at.

Native capture is rrweb DOM events, not a screen recording. v1 exposes two first-class formats plus optional legacy video:

1. formats.player — a signed HTML page that mounts the same rrweb player as the dashboard Replay tab. Valid 24 hours. Zero extra storage.
2. formats.rrweb — signed JSON manifest + ordered chunk files (24 hours). Concatenate chunk event arrays in order and feed them to any rrweb player.
3. formats.video — present only when a historical MP4 already exists on the row. v1 does not transcode rrweb to MP4. Typical status: not_generated.

formats.still is the report screenshot (30-minute TTL). timeline is the widget action log (clicks, navigation, masked input, JS errors) — a separate, smaller JSON array from rrweb.

Reports without a recording still return HTTP 200 with has_replay: false. HTTP 404 means the report is not in the key’s project.

• Issued exclusively by authenticated GET /api/v1/feedback/:id and …/replay for a report in the same project as the key.
• HMAC-SHA256 over an expiry-bearing payload. Tokens are opaque; clients must not parse them.
• Claims include project id, report id, API key id, and Unix expiry. Revoking the key invalidates every outstanding player URL that was minted with it, even before the 24-hour TTL.
• Expired, forged, or revoked tokens → 404/410. The watch page does not require a dashboard login (so a browser or a browser-capable agent can open it). Possession of the URL is the credential until expiry or revocation.
• Response headers: Cache-Control: private, no-store, Referrer-Policy: no-referrer, X-Frame-Options: DENY, Content-Security-Policy: frame-ancestors 'none', X-Robots-Tag: noindex, nofollow, X-Content-Type-Options: nosniff. The player cannot be embedded in a third-party iframe and is not offered to search engines.

The HTML player loads events from an internal GET /api/replay-watch/:token stream (IP-throttled, same security headers). That route is not part of the v1 contract; integrate against formats.player.watch.url or formats.rrweb.

Confirms the key and returns the project it is bound to. Use this as a connectivity check before listing reports.

{
  "project": {
    "id": "11111111-2222-4333-8444-555555555555",
    "name": "Client site",
    "site_url": "https://staging.example.com"
  }
}

Lightweight index of reports in the project. It never includes recording_events, console_logs, conversation, activity, or signed file URLs. Use detail / assets / replay for those.

{
  "data": [
    {
      "id": "aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee",
      "pin_number": 4,
      "status": "aperto",
      "priority": "bloccante",
      "category": "bug",
      "feedback_type": "debug_replay",
      "title": "Checkout does not submit the order",
      "comment": "I click Pay and nothing happens.",
      "client_title": null,
      "page_url": "https://staging.example.com/checkout",
      "page_path": "/checkout",
      "created_at": "2026-10-01T14:12:00.000Z",
      "updated_at": "2026-10-01T15:40:00.000Z",
      "last_activity_at": "2026-10-01T15:40:00.000Z",
      "author_name": "Anna",
      "assigned_to": null,
      "has_screenshot": true,
      "has_replay": true,
      "has_attachments": true,
      "has_console_errors": true,
      "attachment_count": 1
    }
  ],
  "next_cursor": null,
  "has_more": false
}

Full solving context for one report in the key’s project. Optional query include=recording_events adds the widget timeline. rrweb events are never inlined; use the signed URLs under replay.

GET /api/v1/feedback/aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee?include=recording_events
Authorization: Bearer $FIXNOTY_API_KEY

Re-mints signed URLs without re-downloading comments, conversation, or activity. Top-level expires_in is the screenshot/attachment TTL (1800s). replay_expires_in is the player/rrweb TTL (86400s).

{
  "data": {
    "screenshot": {
      "url": "https://….supabase.co/storage/v1/object/sign/feedback-screenshots/…?token=redacted",
      "expires_in": 1800,
      "expires_at": "2026-10-02T10:30:00.000Z"
    },
    "attachments": [],
    "debug_attachments": [],
    "replay": null
  },
  "expires_in": 1800,
  "replay_expires_in": 86400
}

Dedicated replay envelope. Widget timeline is included by default. Open formats.player.watch.url in a browser to see the session exactly as in the dashboard.

{
  "data": {
    "feedback_id": "aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee",
    "has_replay": true,
    "duration_seconds": 42,
    "recording_session_id": null,
    "debug_session_id": "bbbbbbbb-cccc-4ddd-8eee-ffffffffffff",
    "expires_in": 86400,
    "formats": {
      "rrweb": {
        "available": true,
        "playback": "rrweb",
        "expires_in": 86400,
        "manifest": {
          "url": "https://….supabase.co/storage/v1/object/sign/debug-replays/…?token=redacted",
          "expires_in": 86400,
          "expires_at": "2026-10-03T10:00:00.000Z"
        },
        "chunks": [
          {
            "url": "https://…/chunk-000.json?token=redacted",
            "expires_in": 86400,
            "expires_at": "2026-10-03T10:00:00.000Z"
          }
        ]
      },
      "player": {
        "available": true,
        "playback": "player",
        "expires_in": 86400,
        "watch": {
          "url": "https://www.fixnoty.com/it/replay/<signed-token>",
          "expires_in": 86400,
          "expires_at": "2026-10-03T10:00:00.000Z"
        }
      },
      "video": {
        "available": false,
        "playback": "mp4",
        "status": "not_generated",
        "mime_type": "video/mp4",
        "expires_in": 86400,
        "file": null
      },
      "still": {
        "url": "https://….supabase.co/storage/v1/object/sign/feedback-screenshots/…?token=redacted",
        "expires_in": 1800,
        "expires_at": "2026-10-02T10:30:00.000Z"
      }
    },
    "timeline": [
      {
        "t": 1200,
        "at": "2026-10-01T14:12:01.200Z",
        "type": "click",
        "page_url": "https://staging.example.com/checkout"
      }
    ],
    "warnings": []
  },
  "expires_in": 86400
}

This API is a data channel. It does not call a model and does not auto-fix reports.

• Text-only LLM. Read list + detail JSON, console logs, timeline, and conversation. You get actions, errors, copy, and one still frame. You do not get motion.
• Browser-capable agent. Open formats.player.watch.url, press play, and screenshot or watch the reconstructed DOM. A bare HTTP GET of that URL returns the player HTML/JS shell, not video frames.
• Custom player. Download formats.rrweb chunks. Same events the dashboard uses.

We do not generate MP4 from rrweb: it would duplicate storage already held as event chunks. The 24-hour player reuses those chunks.

• This documentation URL is public on purpose. Public docs describe the contract. They do not grant access.
• Access control is the project API key (hashed at rest) plus server-side project_id filters. Guessing another project’s report UUID cannot leak it.
• Dashboard RLS: only the owner can select/insert/update rows in project_api_keys.
• Player links are unlisted, unindexed, non-embeddable, time-bounded, and key-revocable. Do not forward them.
• Do not put API keys in frontend bundles or in Referer-leaking pages. Prefer server-side callers.

Current version: v1. Additive fields may appear. The following are explicitly out of v1:

• POST / PATCH / DELETE (status, comments, assignment)
• Synchronous zip of a whole project
• Billing, paid rate plans, webhooks
• Official SDKs and OpenAPI
• Model inference, auto-fix, or outbound AI webhooks
• MP4 transcode from rrweb

Canonical public reference: this page. A matching technical note lives in the repository at docs/api-v1.md. Browser “Print → Save as PDF” is supported; we do not ship a separately versioned PDF that can drift from the implementation.