request_media_download

Request media download

Describe the required authenticated bounded companion download.

Authorization and permissions

Requires a valid delegated OAuth token and access to the selected workspace.

OAuth scope: mcp:read
Workspace requirement: Authorized workspace and current membership required

Current workspace member.

Input schema

{
  "additionalProperties": false,
  "properties": {
    "media_id": {
      "description": "Media id.",
      "minimum": 1,
      "type": "integer"
    },
    "post_id": {
      "description": "Public post sqid.",
      "maxLength": 32,
      "minLength": 1,
      "type": "string"
    },
    "team_id": {
      "description": "Consented workspace ID.",
      "minimum": 1,
      "type": "integer"
    }
  },
  "required": [
    "team_id",
    "post_id",
    "media_id"
  ],
  "type": "object"
}

Result schema

{
  "additionalProperties": false,
  "properties": {
    "concurrency": {
      "description": "Concurrency.",
      "type": "string"
    },
    "filename": {
      "description": "Filename.",
      "type": "string"
    },
    "headers": {
      "additionalProperties": false,
      "description": "Headers.",
      "properties": {
        "Authorization": {
          "const": "Bearer",
          "description": "Authorization."
        }
      },
      "required": [
        "Authorization"
      ],
      "type": "object"
    },
    "method": {
      "const": "GET",
      "description": "Method."
    },
    "url": {
      "description": "Url.",
      "type": "string"
    }
  },
  "required": [
    "method",
    "url",
    "headers",
    "filename",
    "concurrency"
  ],
  "type": "object"
}

Example arguments

{
  "media_id": 615,
  "post_id": "P7k2Lm9Q",
  "team_id": 42
}

Example result

{
  "concurrency": "The endpoint rechecks the delegated workspace membership on every download.",
  "filename": "onboarding-checklist.pdf",
  "headers": {
    "Authorization": "Bearer"
  },
  "method": "GET",
  "url": "/mcp/transfers/media/42/P7k2Lm9Q/615/"
}

Errors and retry

Requires current workspace membership. Unknown posts, media, accounts, and cross-workspace IDs return not found. Upload commit, rename, and delete recheck edit permission, approval confirmation, and the post version; invalid type, size, or title is rejected. Calls are limited to 120 per user per minute.

Metadata reads and transfer-instruction requests are safe to retry, but transfer URLs still require the delegated bearer credential (the example is an instruction, not a token). After an ambiguous upload or mutation, list media and reload the post version before retrying; delete is not safe to repeat after success.

Effects, limits, and source

Workspace roles, subscription and AI usage limits, approval rules, and server rate limits are enforced at call time. Rate-limit responses identify when to retry; scheduled work returns state rather than holding the request open.

social_scheduling.api.media_file; companion transfer owned by runtime