Currents Frames API

openapi: 3.2.0
info:
  title: Currents trace Frames 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: Frames
paths:
  /{slug}/frames:
    get:
      summary: Screencast timeline metadata
      description: Frame count, time bounds, dimensions, and per-frame timestamps — drives scrubbers and tells you which timestamps exist before requesting frames. Also playwrightVersion (e.g. 1.64.0-alpha-1790635538000) and traceFormatVersion (e.g. 10), each null when the trace does not record it, to pick a trace viewer that can open the trace. A trace without screencast frames answers with frameCount 0.
      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: Screencast timeline metadata (application/json)
          headers:
            x-dashboard-url:
              description: The test’s page in the Currents dashboard, when the link names one. Opening it needs a login to the organization.
              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:
      - Frames
      operationId: getBySlugFrames
      x-operation-id-source: derived
  /{slug}/frames/failure:
    get:
      summary: The screencast frame at the failure
      description: 'The frame 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 frame. Takes the same parameters as frames/{t}, 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: jpeg (default, stored bytes as-is) or webp
        schema:
          type: string
          enum:
          - jpeg
          - webp
      - name: width
        in: query
        required: false
        description: scale to exactly this width (implies webp)
        schema:
          type: integer
          minimum: 16
          maximum: 3840
      - name: placeholder
        in: query
        required: false
        description: '`1` returns 200 with a grey 16:9 SVG at the requested width (480 without a valid one) in place of an error response. The `x-placeholder` header names the reason: `routeError` for no screencast frames, a frame missing from the zip, a bad parameter, 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 screencast frame at the failure (image/jpeg | image/webp | image/svg+xml)
          headers:
            content-location:
              description: exact timestamp of the served frame, as a sibling URL
              schema:
                type: string
            x-trace-timestamp:
              description: trace timestamp of the served frame
              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:
      - Frames
      operationId: getBySlugFramesFailure
      x-operation-id-source: derived
  /{slug}/frames/{t}:
    get:
      summary: One screencast frame as an image
      description: The frame at or before trace timestamp {t}. By default the stored JPEG is passed through untouched; format=webp or width= re-encodes as WebP, scaled to exactly that width — upscaling beyond the stored frame size too.
      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: t
        in: path
        required: true
        description: Trace timestamp in ms; resolves to the frame at or before it.
        schema:
          type: string
      - name: format
        in: query
        required: false
        description: jpeg (default, stored bytes as-is) or webp
        schema:
          type: string
          enum:
          - jpeg
          - webp
      - name: width
        in: query
        required: false
        description: scale to exactly this width (implies webp)
        schema:
          type: integer
          minimum: 16
          maximum: 3840
      responses:
        '200':
          description: One screencast frame as an image (image/jpeg | image/webp)
          headers:
            content-location:
              description: exact timestamp of the served frame, as a sibling URL
              schema:
                type: string
            x-trace-timestamp:
              description: trace timestamp of the served frame
              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:
      - Frames
      operationId: getBySlugFramesByT
      x-operation-id-source: derived
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer