# Upload a sandbox recording (https://orgasm.dev/docs/api/sandbox/uploadSandboxRecording)

# Upload a sandbox recording

- **Method:** `PUT`
- **Path:** `/v1/sandbox/uploads/{uploadToken}`
- **Operation ID:** `uploadSandboxRecording`
- **Tags:** sandbox

The target of `uploads.face.url` and `uploads.body.url` in test mode.
The sandbox reads and discards the bytes without storing them, then
starts the recording's scenario. Do not upload real recordings of
people to the sandbox; any small video file works. In live mode the
upload URL points at the enclave instead.

## Effective servers

- `https://orgasm.dev`

  `sk_test_` keys reach the sandbox. `sk_live_` keys are refused until live analysis is available.
- `http://localhost:3000`

  The docs site running locally (`npm run dev`), which serves the sandbox.
- `http://localhost:4010`

  The standalone sandbox (`npm run mock`), which also serves the WebSocket channel.

## Authentication

No authentication required.

## Path parameters

- **`uploadToken` (required)**: `string`, pattern: `^up_[0-9a-z]{24}$`

  The token in a sandbox `uploads.*.url`.

## Request body

The video file. Its bytes are read and discarded.

**Required:** `true`

**Content type:** `video/mp4`

`string`

**Example:**

```json
""
```

**Content type:** `video/quicktime`

`string`

**Example:**

```json
""
```

**Content type:** `application/octet-stream`

`string`

**Example:**

```json
""
```

## Responses

### 200 The upload was accepted.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/json`

schema: `UploadReceipt`

Confirms a sandbox upload.

- **`bytesReceived` (required)**: `integer`
- **`object` (required)**: `string`, const: `"upload_receipt"`
- **`recordingId` (required)**: `string`
- **`view` (required)**: `string`, possible values: `"face", "body"`

**Example:**

```json
{
  "object": "upload_receipt",
  "recordingId": "",
  "view": "face",
  "bytesReceived": 1
}
```

### 404 No such resource for this key's mode.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

schema: `Problem`

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

- **`code` (required)**: `string`, possible values: `"invalid_request", "consent_required", "capability_required", "sandbox_only", "authentication_required", "invalid_api_key", "live_mode_unavailable", "credits_exhausted", "permission_denied", "not_found", "idempotency_key_reused", "session_ended", "sandbox_no_media", "upload_already_received", "payload_too_large", "rate_limited", "capacity_unavailable", "internal_error"`

  A stable, machine-readable error code.
- **`status` (required)**: `integer`

  The HTTP status code.
- **`title` (required)**: `string`

  A short summary of the error.
- **`type` (required)**: `string`, format: `uri`

  A link to the docs for this error.
- **`detail`**: `string`

  What went wrong in this request, and what to do.
- **`errors`**: `array`

  Each contract violation, when the body or a parameter did not match the contract.

  **Items:**
  - **`location` (required)**: `string`, possible values: `"path", "query", "header", "cookie", "body"`
  - **`message` (required)**: `string`
  - **`path` (required)**: `string`

    JSON pointer to the value at fault.
- **`instance`**: `string`

  The request path.
- **`param`**: `string | null`

  The request field at fault, as a dotted path, when there is one.
- **`requestId`**: `string`

**Example:**

```json
{
  "type": "https://orgasm.dev/docs/guides/errors#not_found",
  "title": "Not found",
  "status": 404,
  "code": "not_found",
  "detail": "No live session ls_8f3kq2m7x9w4c1n6t5ra in test mode.",
  "requestId": "req_3k6m9q2t5w8z1c4f7h0j"
}
```

### 409 The request conflicts with the resource's state, or an idempotency key was reused.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

*Schema `Problem` is shown above.*

**Example:**

```json
{
  "type": "https://orgasm.dev/docs/guides/errors#session_ended",
  "title": "The session has ended",
  "status": 409,
  "code": "session_ended",
  "detail": "ls_8f3kq2m7x9w4c1n6t5ra ended at 2026-10-16T14:12:00Z.",
  "requestId": "req_3k6m9q2t5w8z1c4f7h0j"
}
```

### 413 The upload is larger than \`maxBytes\`.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

*Schema `Problem` is shown above.*

**Example:**

```json
{
  "type": "",
  "title": "",
  "status": 1,
  "detail": "",
  "instance": "",
  "code": "invalid_request",
  "param": null,
  "requestId": "",
  "errors": [
    {
      "location": "path",
      "path": "",
      "message": ""
    }
  ]
}
```

## Schemas

- `Problem` — shown above.

### ErrorCode

**Type:** `string`, possible values: `"invalid_request", "consent_required", "capability_required", "sandbox_only", "authentication_required", "invalid_api_key", "live_mode_unavailable", "credits_exhausted", "permission_denied", "not_found", "idempotency_key_reused", "session_ended", "sandbox_no_media", "upload_already_received", "payload_too_large", "rate_limited", "capacity_unavailable", "internal_error"`

A stable, machine-readable error code.

- `UploadReceipt` — shown above.
