Currents Filmstrip API

openapi: 3.2.0
info:
  title: Currents trace Filmstrip 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: Filmstrip
paths:
  /{slug}/filmstrip:
    get:
      summary: The whole run as one contact sheet
      description: Samples frames evenly across the attempt (up to the failure with end=failure) and composes them into one WebP, a near-square grid or a single row — one image request that shows the run, sized for vision models and previews. A strip wider or taller than 16383px (the WebP limit) is a 400.
      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: frames
        in: query
        required: false
        description: tile count
        schema:
          type: integer
          minimum: 2
          maximum: 25
          default: 9
      - name: width
        in: query
        required: false
        description: per-tile width
        schema:
          type: integer
          minimum: 64
          maximum: 1280
          default: 320
      - name: height
        in: query
        required: false
        description: 'cap on each tile’s height: a frame is scaled to fit within width × height, so portrait frames stay short'
        schema:
          type: integer
          minimum: 16
          maximum: 1280
      - name: layout
        in: query
        required: false
        description: grid (default, near-square) or row (every tile in one row)
        schema:
          type: string
          enum:
          - grid
          - row
      - name: end
        in: query
        required: false
        description: '`failure`: sample only up to the frame frames/failure serves and outline that last tile in red; when nothing failed, the whole attempt with no outline'
        schema:
          type: string
          enum:
          - failure
      - name: placeholder
        in: query
        required: false
        description: '`1` returns 200 with a grey SVG of one 16:9 tile fitted within width × height (width 320 when `width` is missing or invalid; no height cap when `height` is missing or invalid) in place of an error response. The `x-placeholder` header names the reason: `routeError` for no screencast frames, a bad parameter, a strip over 16383px, 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 whole run as one contact sheet (image/webp | image/svg+xml)
          headers:
            x-filmstrip-timestamps:
              description: JSON array of each tile’s trace timestamp; not sent on a placeholder answer
              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:
      - Filmstrip
      operationId: getBySlugFilmstrip
      x-operation-id-source: derived
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer