POST /recordings — Upload a Recording

Upload a browser recording to the Claude Scope API and receive a fully analyzed session with a generated agent-ready system prompt.

The POST /recordings endpoint is the core of the Claude Scope API. You upload a video file alongside a few metadata fields, and the endpoint synchronously runs the full dual-lane analysis pipeline — frame extraction, Vision AI analysis, Playwright ARIA inspection, and prompt synthesis — then returns the complete result. Because the endpoint runs the full pipeline before responding, requests may take several seconds to complete depending on video length and the number of URLs inspected.

This is a synchronous endpoint. It does not return until processing is fully complete. Plan your timeout settings accordingly — recordings that are close to the 100 MB limit or that inspect many URLs may take 30 seconds or more.

Endpoint

POST https://api.claudescope.ai/api/recordings

Request

The request body must be multipart/form-data. Do not set Content-Type: application/json — let your HTTP client set the multipart boundary automatically.

Form fields

file · binary · required

The video file to upload and analyze. Accepted MIME types: video/webm, video/mp4, video/x-matroska. Maximum size: 100 MB.

title · string · required

A human-readable title for the session. Displayed in the Claude Scope dashboard and included in the generated prompt. Maximum 500 characters.

seedUrl · string · required

The URL to inspect with the Playwright ARIA snapshot. This should be the starting URL of the flow you recorded — typically the page where the bug or interaction begins. Must include the protocol (http:// or https://).

notes · string

Optional free-text context for the agent prompt. Use this to describe the bug, expected behavior, or any other detail that will help the coding agent understand the task. Maximum 2000 characters.

agentTarget · string · default: "CLAUDE_CODE"

The AI coding agent the generated prompt is formatted for. One of: CLAUDE_CODE, CODEX, CURSOR, RAW. Each value produces a differently structured prompt optimized for that agent’s context format. Defaults to CLAUDE_CODE when omitted.

Response

The response is a ProcessingResponse object. The HTTP status code is 200 OK on success.

sessionId · string · required

Unique identifier for the newly created session. Use this ID with the Sessions API to retrieve or manage the session later. Example: sess_ABC12345.

status · string · required

Processing outcome. Always complete on a successful response. If processing fails the endpoint returns an error status code rather than a status: "error" body.

title · string · required

The title you submitted, echoed back in the response.

seedUrl · string · required

The seed URL you submitted, echoed back in the response.

agentTarget · string · required

The agent target used during synthesis, e.g. CLAUDE_CODE.

fileSize · number · required

Size of the uploaded video file in bytes.

mimeType · string · required

MIME type of the uploaded file as detected by the server, e.g. video/webm.

prompt · string · required

The generated system prompt, formatted for your chosen agentTarget. This is the text you paste into your AI coding agent.

frames · Frame[] · required

Array of extracted frames. Each frame represents a meaningful UI change detected by SSIM differencing.

Show Frame properties

id · string

Unique frame identifier.

sessionId · string

ID of the parent session.

timestamp · number

Position of the frame within the video in milliseconds.

url · string

The URL active in the browser tab at the time this frame was captured.

thumbnailUrl · string

Base64-encoded data URL of the frame thumbnail (e.g. data:image/png;base64,...).

diffSummary · object

Summary of ARIA tree changes between this frame and the previous one.

Show diffSummary properties

added · number

Number of ARIA nodes added.

changed · number

Number of ARIA nodes changed.

removed · number

Number of ARIA nodes removed.

ariaTree · ARIANode[]

ARIA accessibility tree for this frame as an array of nodes.

createdAt · string

ISO 8601 timestamp for when the frame record was created.

frameCount · number · required

Total number of frames extracted from the video.

urlsInspected · string[] · required

Array of URLs that were inspected by the Playwright lane.

processingMs · number · required

Total time taken to process the upload end-to-end, in milliseconds.

inspection · object · required

Summary of the Playwright ARIA inspection run.

Show inspection properties

urlsInspected · string[]

URLs inspected during the Playwright run.

snapshots · object[]

Per-URL inspection results including element counts and success status.

Show snapshot properties

url · string

The URL that was inspected.

success · boolean

Whether the inspection completed without error.

error · string

Error message if the inspection failed.

counts · object

Element counts found on the page.

Show counts properties

buttons · number

Number of button elements.

inputs · number

Number of input elements.

links · number

Number of link elements.

headings · number

Number of heading elements.

images · number

Number of image elements.

total · number

Total count of all interactive elements.

durationMs · number

Time taken for the Playwright inspection in milliseconds.

Example

Request

curl -X POST https://api.claudescope.ai/api/recordings \
  -H "Authorization: Bearer <token>" \
  -F "file=@recording.webm" \
  -F "title=Checkout flow bug" \
  -F "seedUrl=https://your-app.com/checkout" \
  -F "agentTarget=CLAUDE_CODE"

Response

{
  "sessionId": "sess_ABC12345",
  "status": "complete",
  "title": "Checkout flow bug",
  "seedUrl": "https://your-app.com/checkout",
  "agentTarget": "CLAUDE_CODE",
  "fileSize": 4823012,
  "mimeType": "video/webm",
  "prompt": "You are an expert frontend engineer...",
  "frames": [
    {
      "id": "frm_001",
      "sessionId": "sess_ABC12345",
      "timestamp": 1200,
      "url": "https://your-app.com/checkout",
      "thumbnailUrl": "data:image/png;base64,iVBORw0KGgo...",
      "diffSummary": { "added": 2, "changed": 5, "removed": 0 },
      "ariaTree": [
        { "role": "button", "name": "Place order", "children": [] }
      ],
      "createdAt": "2026-04-12T10:23:45.000Z"
    }
  ],
  "frameCount": 4,
  "urlsInspected": ["https://your-app.com/checkout"],
  "processingMs": 14320,
  "inspection": {
    "urlsInspected": ["https://your-app.com/checkout"],
    "snapshots": [
      {
        "url": "https://your-app.com/checkout",
        "success": true,
        "counts": {
          "buttons": 3,
          "inputs": 5,
          "links": 2,
          "headings": 1,
          "images": 0,
          "total": 11
        }
      }
    ],
    "durationMs": 3800
  }
}