# recordings_request_upload

Canonical HTML page: https://bitterclip.com/docs/assistants/tools/recordings_request_upload

Surface: app-only

Product release: 1dce717408a55fac1047e7d779177fa3ef8ede51
Public contract commit: 1ce47f7857ae3d9b6933fe83d5c33de3ae5efc64
Public contract SHA-256: 241d47d25e4b4c1dae9d2263793874d06fc4ba7bc3c78d4cf2bc63fbb32ed7dc
Descriptor SHA-256: 885d46f3ca3939dec2ace0cd6e93611c8b3f741f2d8f7a82e0adfe1452cc9a9e
Captured: 2026-09-24T16:39:30.100Z
Source: https://app.bitterclip.com/api/v1/mcp_descriptors.json

Use this when an agent has a local audio or video file and needs to upload it programmatically. Returns a short-lived direct-to-storage upload grant: either a single PUT URL or multipart part URLs. After the agent uploads the bytes, call recordings_finalize_upload with the upload_token and uploaded part ETags if multipart. To add a device file to a Footage session, pass capture_session_id and its optional relative_path. To add camera footage to an existing episode instead, pass target:{type:"episode", id:"comp_..."}, upload_role:"episode_footage", and batch_id/batch_expected_count/batch_index for the batch; the two targets are mutually exclusive.

The JSON blocks below are the exact MCP descriptor projections served by Rails for the named profiles at capture time. Security schemes and resource URIs may vary by connected host.

## App descriptor

```json
{
  "name": "recordings_request_upload",
  "title": "Request a recording upload grant",
  "description": "Use this when an agent has a local audio or video file and needs to upload it programmatically. Returns a short-lived direct-to-storage upload grant: either a single PUT URL or multipart part URLs. After the agent uploads the bytes, call recordings_finalize_upload with the upload_token and uploaded part ETags if multipart. To add a device file to a Footage session, pass capture_session_id and its optional relative_path. To add camera footage to an existing episode instead, pass target:{type:\"episode\", id:\"comp_...\"}, upload_role:\"episode_footage\", and batch_id/batch_expected_count/batch_index for the batch; the two targets are mutually exclusive.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "filename": {
        "type": "string",
        "description": "Original filename, such as john-questions.mp4."
      },
      "byte_size": {
        "type": "integer",
        "description": "Exact file size in bytes."
      },
      "content_type": {
        "type": "string",
        "description": "Media content type, such as video/mp4 or audio/mpeg."
      },
      "project_id": {
        "type": "string",
        "description": "Optional project public ID to attach the recording to."
      },
      "show_slug": {
        "type": "string",
        "description": "Optional project slug fallback."
      },
      "title": {
        "type": "string",
        "description": "Optional recording title."
      },
      "description": {
        "type": "string",
        "description": "Optional recording description."
      },
      "recorded_at": {
        "type": "string",
        "description": "Optional ISO-8601 recorded timestamp."
      },
      "captured_at": {
        "type": "string",
        "description": "Optional ISO-8601 captured timestamp fallback."
      },
      "last_modified_at": {
        "type": "string",
        "description": "Optional ISO-8601 local file mtime fallback."
      },
      "capture_session_id": {
        "type": "string",
        "description": "Optional Footage-session public ID. The finalized recording joins this session and triggers incremental chronology analysis."
      },
      "relative_path": {
        "type": "string",
        "description": "Optional safe device/folder-relative path retained for a Footage-session upload."
      },
      "target": {
        "type": "object",
        "description": "Optional upload target. For camera footage, pass {type:\"episode\", id:\"comp_...\"}; no source-addressed target is accepted.",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "episode"
            ]
          },
          "id": {
            "type": "string",
            "description": "Existing episode id to receive the camera footage."
          }
        },
        "required": [
          "type",
          "id"
        ]
      },
      "upload_role": {
        "type": "string",
        "enum": [
          "episode_footage"
        ],
        "description": "Set to episode_footage when the uploaded file is camera footage for target episode."
      },
      "batch_id": {
        "type": "string",
        "description": "Shared id for every file added to target episode in one batch."
      },
      "batch_expected_count": {
        "type": "integer",
        "description": "How many files this batch contains. Required with upload_role episode_footage."
      },
      "batch_index": {
        "type": "integer",
        "description": "This file's 0-based position in the batch. Required with upload_role episode_footage."
      }
    },
    "required": [
      "filename",
      "byte_size",
      "content_type"
    ],
    "additionalProperties": false
  },
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": false,
    "idempotentHint": false,
    "openWorldHint": true
  },
  "securitySchemes": [
    {
      "type": "noauth"
    }
  ],
  "_meta": {
    "securitySchemes": [
      {
        "type": "noauth"
      }
    ],
    "ui": {
      "visibility": [
        "app"
      ]
    },
    "openai/widgetAccessible": true,
    "openai/visibility": "private"
  },
  "outputSchema": {
    "type": "object",
    "properties": {
      "upload_strategy": {
        "type": "string",
        "enum": [
          "single_put",
          "multipart"
        ]
      },
      "upload_url": {
        "type": [
          "string",
          "null"
        ],
        "description": "Single PUT URL when upload_strategy is single_put."
      },
      "upload_token": {
        "type": "string"
      },
      "expires_at": {
        "type": "string"
      },
      "headers": {
        "type": "object"
      },
      "part_size": {
        "type": [
          "integer",
          "null"
        ]
      },
      "part_count": {
        "type": [
          "integer",
          "null"
        ]
      },
      "parts": {
        "type": "array",
        "description": "Multipart upload part grants when upload_strategy is multipart."
      }
    },
    "required": [],
    "additionalProperties": false
  }
}
```

## Errors

```json
[
  "billing_required",
  "email_verification_required",
  "file_too_large",
  "upload_not_configured",
  "invalid_input"
]
```

## Examples

```json
[]
```