Currents Snapshots API

openapi: 3.2.0
info:
  title: Currents trace Snapshots API
  version: '1'
  description: On-demand access to Playwright trace contents (screencast frames, trace summary, DOM snapshots, network requests, attachments) via ranged zip reads. Human-readable docs at /docs.
servers:
- url: https://t.crts.sh
tags:
- name: Snapshots
paths:
  /{slug}/snapshots:
    get:
      summary: Catalog of DOM snapshots
      description: 'Every addressable snapshot: exact t, name, capture phase (before|input|after relative to its action), callId (joins the trace summary''s actions), and frame url. Use the name or t as the {id} in the item route.'
      parameters:
      - name: slug
        in: path
        required: true
        description: Link slug minted by the Currents backend; grants read access to one trace until the link expires.
        schema:
          type: string
          pattern: ^[A-Za-z0-9_-]{16}$
      responses:
        '200':
          description: Catalog of DOM snapshots (application/json)
        '400':
          description: invalid parameters
        '404':
          description: unknown or expired link, or not found in this trace
        '413':
          description: the trace is larger than the worker can read
        '422':
          description: the trace artifact is not a readable zip
        '502':
          description: the trace could not be fetched from storage
        '503':
          description: this deployment has no link bucket bound, so no link can be read
      tags:
      - Snapshots
      operationId: getBySlugSnapshots
      x-operation-id-source: derived
  /{slug}/snapshots/failure:
    get:
      summary: The DOM snapshot at the failure
      description: 'The snapshot at or before the moment the test failed: the end of the last action that failed in the step where the test error was recorded, so a caught error in an earlier step or an earlier toPass retry does not count; if none failed there, the end of the action running when the test error was recorded, or the next action event if it never ends (a timeout fails no action); otherwise the next action event after the test error; with no test error, the first action that failed; failing that, the last snapshot. Takes the same formats as snapshots/{id}, plus placeholder, and sends the same headers, except on a placeholder answer.'
      parameters:
      - name: slug
        in: path
        required: true
        description: Link slug minted by the Currents backend; grants read access to one trace until the link expires.
        schema:
          type: string
          pattern: ^[A-Za-z0-9_-]{16}$
      - name: format
        in: query
        required: false
        description: how to render the snapshot
        schema:
          type: string
          enum:
          - json
          - dom
          - html
          - aria
          - text
      - name: placeholder
        in: query
        required: false
        description: '`1` returns 200 with a short HTML page (format=html only; other formats keep their error) in place of an error response. The `x-placeholder` header names the reason: `routeError` for no snapshot, a snapshot whose root refers to one the trace does not have, cached like any response; `notFound` for an unknown, malformed or expired link and `unavailable` for a storage or read error or an unexpected error, both sent with `cache-control: no-cache`. Default: unset, so errors keep their status. Other values are ignored.'
        schema:
          type: string
          enum:
          - '1'
      responses:
        '200':
          description: The DOM snapshot at the failure (application/json | text/plain | text/html)
          headers:
            content-location:
              description: exact id of the snapshot used, as a sibling URL
              schema:
                type: string
            x-trace-timestamp:
              description: timestamp of the snapshot used
              schema:
                type: string
            x-placeholder:
              description: the reason for a placeholder answer (routeError, notFound or unavailable); not sent on other answers
              schema:
                type: string
        '400':
          description: invalid parameters
        '404':
          description: unknown or expired link, or not found in this trace
        '413':
          description: the trace is larger than the worker can read
        '422':
          description: the trace artifact is not a readable zip
        '502':
          description: the trace could not be fetched from storage
        '503':
          description: this deployment has no link bucket bound, so no link can be read
      tags:
      - Snapshots
      operationId: getBySlugSnapshotsFailure
      x-operation-id-source: derived
  /{slug}/snapshots/{id}:
    get:
      summary: One DOM snapshot, rendered by format
      description: '{id} is a snapshot name from the catalog (exact) or a trace timestamp in ms (snapshot at or before). Formats: json (default) — the catalog entry plus available formats; dom — the reconstructed markup as inert text, for reading and diffing; html — a browser-renderable styled page like the Playwright trace viewer''s (stylesheets inlined from the trace''s CSSOM captures, subresources rewritten to captured request bodies, scripts stripped, CSP-locked); aria — an approximate aria tree (static roles/accessible names; no layout, so visibility is best-effort); text — readable page text with interactive markers.'
      parameters:
      - name: slug
        in: path
        required: true
        description: Link slug minted by the Currents backend; grants read access to one trace until the link expires.
        schema:
          type: string
          pattern: ^[A-Za-z0-9_-]{16}$
      - name: id
        in: path
        required: true
        description: Snapshot name or timestamp; for attachments, a sha1 content hash or an attachment name.
        schema:
          type: string
      - name: format
        in: query
        required: false
        description: how to render the snapshot
        schema:
          type: string
          enum:
          - json
          - dom
          - html
          - aria
          - text
      responses:
        '200':
          description: One DOM snapshot, rendered by format (application/json | text/plain | text/html)
          headers:
            content-location:
              description: exact id of the snapshot used, as a sibling URL
              schema:
                type: string
            x-trace-timestamp:
              description: timestamp of the snapshot used
              schema:
                type: string
        '400':
          description: invalid parameters
        '404':
          description: unknown or expired link, or not found in this trace
        '413':
          description: the trace is larger than the worker can read
        '422':
          description: the trace artifact is not a readable zip
        '502':
          description: the trace could not be fetched from storage
        '503':
          description: this deployment has no link bucket bound, so no link can be read
      tags:
      - Snapshots
      operationId: getBySlugSnapshotsById
      x-operation-id-source: derived
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer