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

---
title: Assets and uploads
description: List saved media and prepare an owner upload.
section: reference
order: 40
status: implemented
mode: both
generated: true
sourceOfTruth: [src/lib/mcp/agent-tools.ts, src/lib/server/mcp/AgentMcp.ts, src/lib/docs/handoffs.ts, src/lib/docs/channels.ts]
tools: [list_assets, start_media_upload, get_media_upload, list_media_uploads]
---

Assets are saved media metadata. `list_assets` does not verify bytes or return a preview. `start_media_upload` creates an upload for one MP4 video, or one JPEG or PNG image. Without Publish the owner sends an MP4 at `/media/upload`. With Publish, `directUpload` supplies a signed HTTP PUT URL valid for 15 minutes; send bytes with `Content-Type: video/mp4`, `image/jpeg` or `image/png`, and `Content-Length`. The `Content-Type` decides the kind. Replay the same request ID and label for a fresh URL. Read `get_media_upload` or `list_media_uploads` to resume. An unknown transfer needs explicit recovery, not a replacement upload.

Quoted text is the tool description your client receives from `tools/list`.

## Tools on this page

- [`list_assets`](#list_assets)
- [`start_media_upload`](#start_media_upload)
- [`get_media_upload`](#get_media_upload)
- [`list_media_uploads`](#list_media_uploads)

---

### list_assets {#list_assets}

<div class="doc-fact-strip"><dl><dt>Title</dt><dd>List Media Assets <em>as sent in tools/list</em></dd><dt>Transport</dt><dd>Streamable HTTP at <code>/mcp</code></dd><dt>Annotations</dt><dd><span class="doc-chip" data-kind="annotation" data-value="readOnlyHint:true">readOnlyHint true</span> <span class="doc-chip" data-kind="annotation" data-value="destructiveHint:false">destructiveHint false</span> <span class="doc-chip" data-kind="annotation" data-value="idempotentHint:true">idempotentHint true</span> <span class="doc-chip" data-kind="annotation" data-value="openWorldHint:false">openWorldHint false</span> <em>as sent in tools/list</em></dd><dt>Owner handoff</dt><dd>No</dd><dt>Idempotency key</dt><dd>None</dd><dt>Revision guard</dt><dd>None</dd></dl></div>

> List saved media metadata in the selected workspace. This does not verify bytes, fetch media, or provide a preview.

#### Input

| Field | Type | Required | Constraints |
| --- | --- | --- | --- |
| `workspaceId` | string (UUID) | yes |  |
| `cursor` | string | no | min length 1; max length 1024 |
| `limit` | integer | no | min 1; max 100; default `25` |

Unknown fields are rejected.

#### Result

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `assets` | array of object | yes |  |
| `nextCursor` | string or null | yes |  |
| `preview` | object | yes |  |

The result carries no other fields.

**`assets[]`**

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `id` | string | yes |  |

Other fields may be present. Do not assume they are absent.

**`preview.*`**

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `available` | **always** `false` | yes |  |

The result carries no other fields.

Every successful result is also returned as `structuredContent`.

---

### start_media_upload {#start_media_upload}

<div class="doc-fact-strip"><dl><dt>Title</dt><dd>Start a Media Upload <em>as sent in tools/list</em></dd><dt>Transport</dt><dd>Streamable HTTP at <code>/mcp</code></dd><dt>Annotations</dt><dd><span class="doc-chip" data-kind="annotation" data-value="readOnlyHint:false">readOnlyHint false</span> <span class="doc-chip" data-kind="annotation" data-value="destructiveHint:false">destructiveHint false</span> <span class="doc-chip" data-kind="annotation" data-value="idempotentHint:true">idempotentHint true</span> <span class="doc-chip" data-kind="annotation" data-value="openWorldHint:false">openWorldHint false</span> <em>as sent in tools/list</em></dd><dt>Owner handoff</dt><dd>When directUpload is null; with Publish the agent can send bytes to directUpload.url. <code>/media/upload</code> from <code>uploadUrl</code></dd><dt>Idempotency key</dt><dd><code>requestId</code></dd><dt>Revision guard</dt><dd>None</dd></dl></div>

> Create an upload for one file, subject to the workspace media budget: an MP4 video up to 50 MiB, or a JPEG or PNG image up to 30 MiB and 40,000,000 pixels. uploadUrl is the owner handoff for a video: the owner chooses an MP4 in a signed-in browser. That page takes no image. With Publish (list_workspaces access.canPublish), directUpload is also returned: send the file bytes with one HTTP PUT to directUpload.url before expiresAt, with Content-Length and one Content-Type: video/mp4, image/jpeg or image/png. The Content-Type decides the kind, so this call has no field for it. The server reads the real type, width and height from the bytes and refuses a file that is not the type you declared, an animated image, or a file over the limit. Never put file bytes, paths or storage URLs in MCP arguments. A failed transfer can be sent again to the same URL until it expires. Reuse requestId and label after an uncertain response. Use get_media_upload to read the result.

**When to call it**

Call this when you need a file that ShipContent does not already hold: an MP4 video, or a JPEG or PNG image. Read `media.quota.availableBytes` from `get_onboarding_status` first. This call checks no budget: the workspace budget is checked when file bytes are sent by the owner or an agent with Publish. Five unfinished uploads in the workspace return `UPLOAD_LIMIT_REACHED`; finish or cancel one, then call again. The upload stays open for 24 hours.

With Publish, `directUpload` is a signed HTTP PUT URL with a 15-minute `expiresAt`. It is null without Publish, or when `upload.canUpload` is false. Send one file with one PUT. Always send `Content-Length`. The `Content-Type` of the PUT decides the kind of the upload. This call has no field for the kind.

| File | `Content-Type` | Limit |
| --- | --- | --- |
| Video | `video/mp4` | 50 MiB |
| Image | `image/jpeg` or `image/png` | 30 MiB (31,457,280 bytes) and 40,000,000 pixels |

The server does not trust the declared type. It reads the real type, width and height from the bytes. It refuses a file that is not the declared type, an animated file, a file over 30 MiB and an image over 40,000,000 pixels. A refused image saves no asset and holds no budget. The upload stays `pending` and takes the right file at the same URL. See [Upload an existing image](/docs/workflows/media#upload-an-existing-image) for each refusal and its code.

Replay the same `requestId` and label for a fresh direct URL after expiry. Read saved state before a retry. Updated 2026-10-17: an unresolved storage write or rollback sets `canUpload` to false and produces no fresh direct URL. URL or receiver expiry does not clear that unresolved result. Keep the same request ID.

Updated 2026-11-19: an agent with Publish can upload a JPEG or a PNG. Before this, only an MP4 was accepted. A request that sends only `video/mp4` works as before.

#### Input

| Field | Type | Required | Constraints |
| --- | --- | --- | --- |
| `requestId` | string (UUID) | yes |  |
| `label` | string | yes | min length 1; max length 200 |
| `workspaceId` | string (UUID) | yes |  |

Unknown fields are rejected.

#### Result

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `upload` | object | yes |  |
| `uploadUrl` | string (URL) | yes |  |
| `directUpload` | object or null | yes |  |

The result carries no other fields.

**`upload.*`**

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `id` | string (UUID) | yes |  |
| `assetId` | string (UUID) | yes |  |
| `requestId` | string (UUID) | yes |  |
| `label` | string | yes | min length 1; max length 200 |
| `status` | `"pending"` \| `"receiving"` \| `"storing"` \| `"complete"` \| `"cancelled"` \| `"expired"` | yes |  |
| `manifest` | object (2 shapes) or null | yes |  |
| `metadata` | object (2 shapes) or null | yes |  |
| `createdAt` | string (date-time) | yes |  |
| `expiresAt` | string (date-time) | yes |  |
| `activeUntil` | string (date-time) or null | yes |  |
| `canUpload` | boolean | yes |  |
| `asset` | object or null | yes |  |

The result carries no other fields.

**`upload.asset.*`**

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `id` | string (UUID) | yes |  |
| `name` | string | yes | min length 1; max length 200 |
| `kind` | `"video"` \| `"image"` | yes |  |
| `contentType` | `"video/mp4"` \| `"image/jpeg"` \| `"image/png"` | yes |  |
| `size` | integer | yes | min 1; max 52428800 |
| `width` | integer | yes | max 9007199254740991 |
| `height` | integer | yes | max 9007199254740991 |
| `duration` | number | no |  |
| `source` | **always** `"upload"` | yes |  |
| `createdAt` | string (date-time) | yes |  |

The result carries no other fields.

**`directUpload.*`**

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `url` | string (URL) | yes |  |
| `method` | **always** `"PUT"` | yes |  |
| `expiresAt` | string (date-time) | yes |  |

The result carries no other fields.

Every successful result is also returned as `structuredContent`.

#### Example call

```json
{
  "name": "start_media_upload",
  "arguments": {
    "workspaceId": "00000000-0000-4000-8000-000000000001",
    "requestId": "00000000-0000-4000-8000-000000000014",
    "label": "Product demo, 12 seconds"
  }
}
```

#### Example result

```json
{
  "upload": {
    "id": "00000000-0000-4000-8000-000000000015",
    "assetId": "00000000-0000-4000-8000-000000000012",
    "requestId": "00000000-0000-4000-8000-000000000014",
    "label": "Product demo, 12 seconds",
    "status": "pending",
    "manifest": null,
    "metadata": null,
    "createdAt": "2026-10-05T09:10:00Z",
    "expiresAt": "2026-10-06T09:10:00Z",
    "activeUntil": null,
    "canUpload": true,
    "asset": null
  },
  "uploadUrl": "https://shipcontent.example.com/media/upload?workspaceId=00000000-0000-4000-8000-000000000001&uploadId=00000000-0000-4000-8000-000000000015",
  "directUpload": {
    "url": "https://shipcontent.example.com/mcp/uploads/example-only",
    "method": "PUT",
    "expiresAt": "2026-10-05T09:25:00.000Z"
  }
}
```

#### Errors

- `AUTH_REQUIRED`
- `AUTH_NOT_CONFIGURED`
- `FORBIDDEN`
- `INVALID_INPUT`
- `IDEMPOTENCY_CONFLICT`
- `UPLOAD_LIMIT_REACHED`
- `DATABASE_UNAVAILABLE`

Errors return `isError: true` and `{ code, error }` in `structuredContent`. See [Error codes](/docs/contracts/errors).

#### Replay and conflicts

Reuse the same `requestId` with identical input to recover a lost response; the original result is returned. Changed input with the same ID is rejected. A new ID creates a new operation. See [Request IDs, replay and recovery](/docs/contracts/request-ids).

#### Owner handoff

When directUpload is null; with Publish the agent can send bytes to directUpload.url, use the owner handoff if returned. The owner URL is `uploadUrl` for `/media/upload`. Give that URL to the owner and stop. The URL grants no access by itself.

- What the owner does: Choose an MP4 and send the bytes. The page takes video only.
- What the agent reads: `get_media_upload`, field `upload.status`.

The example direct URL is a nonfunctional placeholder, not a bearer token. Do not put file bytes, paths, credentials or signed URLs in MCP arguments. If `directUpload` is null and `upload.canUpload` is true, give `uploadUrl` to the owner. With Publish, send bytes to `directUpload.url` over HTTP instead. Read `get_media_upload` for `upload.status`.

Updated 2026-11-19: the owner page at `uploadUrl` takes an MP4 only. It does not take images. An agent without Publish cannot upload an image. The owner adds an image in Library with **Upload assets**, or gives Publish to the agent.

`upload.assetId` is reserved when the handoff is created. It is not an asset,
and it is not attachable. Wait for `upload.status` to be `complete` and a non-null `upload.asset`, then use
`upload.asset.id`. Updated 2026-10-17: retention can make an old completed upload
return `asset: null`. Its `canUpload` stays false. Replaying its request ID cannot
restore the removed bytes.

Updated 2026-10-17: releasing storage quota after confirmed retention does not reopen an unfinished receiver. A retired current destination keeps `canUpload: false`, including after account access is restored; it cannot supply a fresh direct URL.

Updated 2026-10-24: a prepared upload cannot accept fresh bytes or start a new storage write after the selected plan expires. Restore plan access before retrying. A storage write that was already dispatched can still record its result and finish the saved upload; the current grant and workspace authority still apply.

#### Related

- [Get media into a workspace](/docs/workflows/media)
- [Error codes](/docs/contracts/errors)
- [/docs/reference/posts](/docs/reference/posts)

---

### get_media_upload {#get_media_upload}

<div class="doc-fact-strip"><dl><dt>Title</dt><dd>Get Media Upload <em>as sent in tools/list</em></dd><dt>Transport</dt><dd>Streamable HTTP at <code>/mcp</code></dd><dt>Annotations</dt><dd><span class="doc-chip" data-kind="annotation" data-value="readOnlyHint:true">readOnlyHint true</span> <span class="doc-chip" data-kind="annotation" data-value="destructiveHint:false">destructiveHint false</span> <span class="doc-chip" data-kind="annotation" data-value="idempotentHint:true">idempotentHint true</span> <span class="doc-chip" data-kind="annotation" data-value="openWorldHint:false">openWorldHint false</span> <em>as sent in tools/list</em></dd><dt>Owner handoff</dt><dd>Yes. <code>/media/upload</code> from <code>uploadUrl</code></dd><dt>Idempotency key</dt><dd>None</dd><dt>Revision guard</dt><dd>None</dd></dl></div>

> Read the saved upload request, owner handoff, and finalized asset if complete. A complete upload returns upload.asset: a video has kind video and a duration; an image has kind image, contentType image/jpeg or image/png, width and height, and no duration. Use upload.asset.id in a post; read get_post_catalogue for the image formats. Upload success proves inspected bytes, not Instagram readiness. A failed transfer returns to pending so the same file can be sent again; never start a replacement upload to hide an uncertain result.

**When to call it**

Call this after `start_media_upload`, or after a PUT with no reply, until `upload.status` is `complete`. A complete upload returns `upload.asset`. Use `upload.asset.id` in a post.

`upload.asset.kind` says what was saved. For a video, `contentType` is `video/mp4` and `duration` is in seconds. For an image, `contentType` is `image/jpeg` or `image/png`, `width` and `height` are the true size in pixels, and there is no `duration`. `upload.manifest.contentType` is present for an image only. `upload.metadata` holds the measured values: `contentType`, `width` and `height` for an image.

An image asset can attach to the image and carousel formats, and to an Instagram story. See [Upload an existing image](/docs/workflows/media#upload-an-existing-image) for the formats that publish today. A complete upload proves inspected bytes. It does not prove that a channel accepts the file.

#### Input

| Field | Type | Required | Constraints |
| --- | --- | --- | --- |
| `workspaceId` | string (UUID) | yes |  |
| `uploadId` | string (UUID) | yes |  |

Unknown fields are rejected.

#### Result

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `upload` | object | yes |  |
| `uploadUrl` | string (URL) | yes |  |

The result carries no other fields.

**`upload.*`**

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `id` | string (UUID) | yes |  |
| `assetId` | string (UUID) | yes |  |
| `requestId` | string (UUID) | yes |  |
| `label` | string | yes | min length 1; max length 200 |
| `status` | `"pending"` \| `"receiving"` \| `"storing"` \| `"complete"` \| `"cancelled"` \| `"expired"` | yes |  |
| `manifest` | object (2 shapes) or null | yes |  |
| `metadata` | object (2 shapes) or null | yes |  |
| `createdAt` | string (date-time) | yes |  |
| `expiresAt` | string (date-time) | yes |  |
| `activeUntil` | string (date-time) or null | yes |  |
| `canUpload` | boolean | yes |  |
| `asset` | object or null | yes |  |

The result carries no other fields.

**`upload.asset.*`**

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `id` | string (UUID) | yes |  |
| `name` | string | yes | min length 1; max length 200 |
| `kind` | `"video"` \| `"image"` | yes |  |
| `contentType` | `"video/mp4"` \| `"image/jpeg"` \| `"image/png"` | yes |  |
| `size` | integer | yes | min 1; max 52428800 |
| `width` | integer | yes | max 9007199254740991 |
| `height` | integer | yes | max 9007199254740991 |
| `duration` | number | no |  |
| `source` | **always** `"upload"` | yes |  |
| `createdAt` | string (date-time) | yes |  |

The result carries no other fields.

Every successful result is also returned as `structuredContent`.

#### Example call

```json
{
  "name": "get_media_upload",
  "arguments": {
    "workspaceId": "00000000-0000-4000-8000-000000000001",
    "uploadId": "00000000-0000-4000-8000-000000000015"
  }
}
```

#### Example result

```json
{
  "upload": {
    "id": "00000000-0000-4000-8000-000000000015",
    "assetId": "00000000-0000-4000-8000-000000000012",
    "requestId": "00000000-0000-4000-8000-000000000014",
    "label": "Store front photo",
    "status": "complete",
    "manifest": {
      "name": "upload.jpg",
      "size": 482113,
      "contentType": "image/jpeg"
    },
    "metadata": {
      "contentType": "image/jpeg",
      "width": 1600,
      "height": 1200
    },
    "createdAt": "2026-11-19T09:10:00.000Z",
    "expiresAt": "2026-11-20T09:10:00.000Z",
    "activeUntil": null,
    "canUpload": false,
    "asset": {
      "id": "00000000-0000-4000-8000-000000000012",
      "name": "upload.jpg",
      "kind": "image",
      "contentType": "image/jpeg",
      "size": 482113,
      "width": 1600,
      "height": 1200,
      "source": "upload",
      "createdAt": "2026-11-19T09:10:07.000Z"
    }
  },
  "uploadUrl": "https://shipcontent.example.com/media/upload?workspaceId=00000000-0000-4000-8000-000000000001&uploadId=00000000-0000-4000-8000-000000000015"
}
```

#### Errors

- `AUTH_REQUIRED`
- `AUTH_NOT_CONFIGURED`
- `FORBIDDEN`
- `INVALID_INPUT`
- `NOT_FOUND`
- `DATABASE_UNAVAILABLE`

Errors return `isError: true` and `{ code, error }` in `structuredContent`. See [Error codes](/docs/contracts/errors).

#### Owner handoff

The owner URL is `uploadUrl` for `/media/upload`. Give that URL to the owner and stop. The URL grants no access by itself.

- What the owner does: Finish an upload that is still open.
- What the agent reads: `get_media_upload`, field `upload.status`.

#### Related

- [Get media into a workspace](/docs/workflows/media)
- [Error codes](/docs/contracts/errors)
- [/docs/reference/assets](/docs/reference/assets)

---

### list_media_uploads {#list_media_uploads}

<div class="doc-fact-strip"><dl><dt>Title</dt><dd>List Media Uploads <em>as sent in tools/list</em></dd><dt>Transport</dt><dd>Streamable HTTP at <code>/mcp</code></dd><dt>Annotations</dt><dd><span class="doc-chip" data-kind="annotation" data-value="readOnlyHint:true">readOnlyHint true</span> <span class="doc-chip" data-kind="annotation" data-value="destructiveHint:false">destructiveHint false</span> <span class="doc-chip" data-kind="annotation" data-value="idempotentHint:true">idempotentHint true</span> <span class="doc-chip" data-kind="annotation" data-value="openWorldHint:false">openWorldHint false</span> <em>as sent in tools/list</em></dd><dt>Owner handoff</dt><dd>No</dd><dt>Idempotency key</dt><dd>None</dd><dt>Revision guard</dt><dd>None</dd></dl></div>

> Discover unfinished upload requests first, then recent history, up to 25 records in this workspace. Use this after reconnecting or losing chat history. Continue an existing owner handoff; completed uploads include the stable asset ID for draft attachment, for a video or an image (upload.asset.kind).

**When to call it**

Call this after you reconnect or lose chat history. It returns up to 25 upload requests of the workspace: unfinished requests first, then recent history. Each item has the same `upload` as `get_media_upload`.

An upload is a video or an image. Read `upload.asset.kind` of a complete upload. An image upload has `upload.manifest.contentType` of `image/jpeg` or `image/png`, and `upload.asset` has no `duration`. An upload that never received a file has `manifest: null`, so its kind is not set yet. The first PUT sets it. A refused image upload returns to that state.

Continue an unfinished upload with the same `requestId` and label in `start_media_upload`. Do not start a replacement upload to bypass an uncertain result.

#### Input

| Field | Type | Required | Constraints |
| --- | --- | --- | --- |
| `workspaceId` | string (UUID) | yes |  |

Unknown fields are rejected.

#### Result

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `uploads` | array of object | yes |  |

The result carries no other fields.

**`uploads[]`**

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `upload` | object | yes |  |
| `uploadUrl` | string (URL) | yes |  |

The result carries no other fields.

**`uploads[].upload.*`**

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `id` | string (UUID) | yes |  |
| `assetId` | string (UUID) | yes |  |
| `requestId` | string (UUID) | yes |  |
| `label` | string | yes | min length 1; max length 200 |
| `status` | `"pending"` \| `"receiving"` \| `"storing"` \| `"complete"` \| `"cancelled"` \| `"expired"` | yes |  |
| `manifest` | object (2 shapes) or null | yes |  |
| `metadata` | object (2 shapes) or null | yes |  |
| `createdAt` | string (date-time) | yes |  |
| `expiresAt` | string (date-time) | yes |  |
| `activeUntil` | string (date-time) or null | yes |  |
| `canUpload` | boolean | yes |  |
| `asset` | object or null | yes |  |

The result carries no other fields.

Every successful result is also returned as `structuredContent`.

#### Errors

- `AUTH_REQUIRED`
- `AUTH_NOT_CONFIGURED`
- `FORBIDDEN`
- `DATABASE_UNAVAILABLE`

Errors return `isError: true` and `{ code, error }` in `structuredContent`. See [Error codes](/docs/contracts/errors).

#### Related

- [Get media into a workspace](/docs/workflows/media)
- [Error codes](/docs/contracts/errors)
- [/docs/reference/assets](/docs/reference/assets)

---

The schemas on this page are generated from the repository at build time. The guidance was last reviewed on 2026-11-19.
