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#
- Title
- List Media Assets as sent in tools/list
- Transport
- Streamable HTTP at
/mcp - Annotations
- readOnlyHint true destructiveHint false idempotentHint true openWorldHint false as sent in tools/list
- Owner handoff
- No
- Idempotency key
- None
- Revision guard
- None
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#
- Title
- Start a Media Upload as sent in tools/list
- Transport
- Streamable HTTP at
/mcp - Annotations
- readOnlyHint false destructiveHint false idempotentHint true openWorldHint false as sent in tools/list
- Owner handoff
- When directUpload is null; with Publish the agent can send bytes to directUpload.url.
/media/uploadfromuploadUrl - Idempotency key
requestId- Revision guard
- None
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 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#
{
"name": "start_media_upload",
"arguments": {
"workspaceId": "00000000-0000-4000-8000-000000000001",
"requestId": "00000000-0000-4000-8000-000000000014",
"label": "Product demo, 12 seconds"
}
}
Example result#
{
"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_REQUIREDAUTH_NOT_CONFIGUREDFORBIDDENINVALID_INPUTIDEMPOTENCY_CONFLICTUPLOAD_LIMIT_REACHEDDATABASE_UNAVAILABLE
Errors return isError: true and { code, error } in structuredContent. See Error codes.
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.
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, fieldupload.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_upload#
- Title
- Get Media Upload as sent in tools/list
- Transport
- Streamable HTTP at
/mcp - Annotations
- readOnlyHint true destructiveHint false idempotentHint true openWorldHint false as sent in tools/list
- Owner handoff
- Yes.
/media/uploadfromuploadUrl - Idempotency key
- None
- Revision guard
- None
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 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#
{
"name": "get_media_upload",
"arguments": {
"workspaceId": "00000000-0000-4000-8000-000000000001",
"uploadId": "00000000-0000-4000-8000-000000000015"
}
}
Example result#
{
"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_REQUIREDAUTH_NOT_CONFIGUREDFORBIDDENINVALID_INPUTNOT_FOUNDDATABASE_UNAVAILABLE
Errors return isError: true and { code, error } in structuredContent. See Error codes.
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, fieldupload.status.
Related#
list_media_uploads#
- Title
- List Media Uploads as sent in tools/list
- Transport
- Streamable HTTP at
/mcp - Annotations
- readOnlyHint true destructiveHint false idempotentHint true openWorldHint false as sent in tools/list
- Owner handoff
- No
- Idempotency key
- None
- Revision guard
- None
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_REQUIREDAUTH_NOT_CONFIGUREDFORBIDDENDATABASE_UNAVAILABLE
Errors return isError: true and { code, error } in structuredContent. See Error codes.
Related#
The schemas on this page are generated from the repository at build time. The guidance was last reviewed on 2026-11-19.