> ## Documentation Index
> Fetch the complete documentation index at: https://claudescope.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Note>
  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.
</Note>

## 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

<ParamField body="file" type="binary" required>
  The video file to upload and analyze. Accepted MIME types: `video/webm`, `video/mp4`, `video/x-matroska`. Maximum size: **100 MB**.
</ParamField>

<ParamField body="title" type="string" required>
  A human-readable title for the session. Displayed in the Claude Scope dashboard and included in the generated prompt. Maximum 500 characters.
</ParamField>

<ParamField body="seedUrl" type="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://`).
</ParamField>

<ParamField body="notes" type="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.
</ParamField>

<ParamField body="agentTarget" type="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.
</ParamField>

## Response

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

<ResponseField name="sessionId" type="string" required>
  Unique identifier for the newly created session. Use this ID with the [Sessions API](/api/sessions) to retrieve or manage the session later. Example: `sess_ABC12345`.
</ResponseField>

<ResponseField name="status" type="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.
</ResponseField>

<ResponseField name="title" type="string" required>
  The title you submitted, echoed back in the response.
</ResponseField>

<ResponseField name="seedUrl" type="string" required>
  The seed URL you submitted, echoed back in the response.
</ResponseField>

<ResponseField name="agentTarget" type="string" required>
  The agent target used during synthesis, e.g. `CLAUDE_CODE`.
</ResponseField>

<ResponseField name="fileSize" type="number" required>
  Size of the uploaded video file in bytes.
</ResponseField>

<ResponseField name="mimeType" type="string" required>
  MIME type of the uploaded file as detected by the server, e.g. `video/webm`.
</ResponseField>

<ResponseField name="prompt" type="string" required>
  The generated system prompt, formatted for your chosen `agentTarget`. This is the text you paste into your AI coding agent.
</ResponseField>

<ResponseField name="frames" type="Frame[]" required>
  Array of extracted frames. Each frame represents a meaningful UI change detected by SSIM differencing.

  <Expandable title="Frame properties">
    <ResponseField name="id" type="string">
      Unique frame identifier.
    </ResponseField>

    <ResponseField name="sessionId" type="string">
      ID of the parent session.
    </ResponseField>

    <ResponseField name="timestamp" type="number">
      Position of the frame within the video in milliseconds.
    </ResponseField>

    <ResponseField name="url" type="string">
      The URL active in the browser tab at the time this frame was captured.
    </ResponseField>

    <ResponseField name="thumbnailUrl" type="string">
      Base64-encoded data URL of the frame thumbnail (e.g. `data:image/png;base64,...`).
    </ResponseField>

    <ResponseField name="diffSummary" type="object">
      Summary of ARIA tree changes between this frame and the previous one.

      <Expandable title="diffSummary properties">
        <ResponseField name="added" type="number">Number of ARIA nodes added.</ResponseField>
        <ResponseField name="changed" type="number">Number of ARIA nodes changed.</ResponseField>
        <ResponseField name="removed" type="number">Number of ARIA nodes removed.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="ariaTree" type="ARIANode[]">
      ARIA accessibility tree for this frame as an array of nodes.
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO 8601 timestamp for when the frame record was created.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="frameCount" type="number" required>
  Total number of frames extracted from the video.
</ResponseField>

<ResponseField name="urlsInspected" type="string[]" required>
  Array of URLs that were inspected by the Playwright lane.
</ResponseField>

<ResponseField name="processingMs" type="number" required>
  Total time taken to process the upload end-to-end, in milliseconds.
</ResponseField>

<ResponseField name="inspection" type="object" required>
  Summary of the Playwright ARIA inspection run.

  <Expandable title="inspection properties">
    <ResponseField name="urlsInspected" type="string[]">
      URLs inspected during the Playwright run.
    </ResponseField>

    <ResponseField name="snapshots" type="object[]">
      Per-URL inspection results including element counts and success status.

      <Expandable title="snapshot properties">
        <ResponseField name="url" type="string">The URL that was inspected.</ResponseField>
        <ResponseField name="success" type="boolean">Whether the inspection completed without error.</ResponseField>
        <ResponseField name="error" type="string">Error message if the inspection failed.</ResponseField>

        <ResponseField name="counts" type="object">
          Element counts found on the page.

          <Expandable title="counts properties">
            <ResponseField name="buttons" type="number">Number of button elements.</ResponseField>
            <ResponseField name="inputs" type="number">Number of input elements.</ResponseField>
            <ResponseField name="links" type="number">Number of link elements.</ResponseField>
            <ResponseField name="headings" type="number">Number of heading elements.</ResponseField>
            <ResponseField name="images" type="number">Number of image elements.</ResponseField>
            <ResponseField name="total" type="number">Total count of all interactive elements.</ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="durationMs" type="number">
      Time taken for the Playwright inspection in milliseconds.
    </ResponseField>
  </Expandable>
</ResponseField>

## Example

### Request

```bash theme={null}
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

```json theme={null}
{
  "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
  }
}
```