Skip to main content
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.
​
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.

​
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
  }
}