Tools

add_footage

Add one file the user owns (an https link, an upload key, or a clip job id) to their footage library and queue indexing. Call it first with confirm omitted: the result is the Clips-minute estimate and nothing is held. Set confirm to true only after the user accepts that estimate. rights must be owned. A private or non-https link is refused. The same file is indexed once.

Access token · edit · Changes account data

Parameters

source string required

Where the file comes from.

View schema

{
  "description": "Where the file comes from.",
  "type": "string",
  "enum": [
    "upload",
    "link",
    "clip_job"
  ]
}

ref string required

An https link, an upload key under your account, or a clip job id.

View schema

{
  "description": "An https link, an upload key under your account, or a clip job id.",
  "type": "string",
  "minLength": 1,
  "maxLength": 2000
}

rights string optional

Required. Say owned only for footage you own or have cleared.

View schema

{
  "description": "Required. Say owned only for footage you own or have cleared.",
  "type": "string",
  "const": "owned"
}

role string optional

reaction, demo, talking_head, b_roll, product, or other.

View schema

{
  "description": "reaction, demo, talking_head, b_roll, product, or other.",
  "type": "string",
  "enum": [
    "reaction",
    "demo",
    "talking_head",
    "b_roll",
    "product",
    "other"
  ]
}

collection string optional

Library folder name.

View schema

{
  "description": "Library folder name.",
  "type": "string",
  "minLength": 1,
  "maxLength": 80
}

title string optional

View schema

{
  "type": "string",
  "maxLength": 240
}

duration_seconds number optional

Length of the file. Required so the minute estimate is the real one.

View schema

{
  "description": "Length of the file. Required so the minute estimate is the real one.",
  "type": "number",
  "exclusiveMinimum": 0,
  "maximum": 10800
}

media_sha string optional

SHA-256 of the file. The same file is indexed once.

View schema

{
  "description": "SHA-256 of the file. The same file is indexed once.",
  "type": "string",
  "pattern": "^[a-f0-9]{64}$"
}

confirm boolean optional

True only after the user has accepted the Clips-minute estimate.

View schema

{
  "description": "True only after the user has accepted the Clips-minute estimate.",
  "type": "boolean"
}

Request example

{
  "name": "add_footage",
  "arguments": {
    "source": "upload",
    "ref": "YOUR_REF"
  }
}

Replace example values with ids and arguments read from your own Heavenly account. This example does not execute a tool.

Returns

The tool result from Heavenly’s workspace, encoded as MCP text content. The connector returns isError when an argument, permission, plan or account check fails.

Account access and permissions are checked by Heavenly. See errors for failure handling.