Upload and download media through the API

Prepare the file

API uploads accept prepared JPEGs or unchanged H.264 MP4 videos. MP4 size must be strictly below 10,000,000 bytes. Read GET /capabilities for current image defaults, platform constraints and storage limits. Use those settings when preparing images.

Use the Node upload helper with Node 22.14 or newer. It prepares images with the supported settings, corrects orientation, removes source metadata and keeps proportions without enlargement. Transparent areas become white.

# Run from the unzipped helper directory.
npm install sharp@0.35.4
# Set CRICKETS_API_TOKEN securely in your environment.
export CRICKETS_WORKSPACE_ID='WORKSPACE_ID'
node --experimental-strip-types scripts/api-upload.mjs '/path/to/photo.png'

Use the multipart flow

1. Call POST /media/uploads with name, type (image/jpeg or video/mp4) and byte size. Save its media ID and part size.
2. Upload sequential binary parts with PUT /media/{id}/parts/{number}. Retain the returned part number and ETag for each part.
3. Call POST /media/{id}/complete with the ordered parts array.
4. Wait for confirmed ready status before using the media ID in a post. Save alt text with PATCH /media/{id} and an alt field.

Completion validates type, dimensions, metadata, actual size and storage allowance. Invalid completion removes the invalid item; correct the source and start again. Referenced attachments are protected from library deletion.

Private downloads and MCP

REST downloads require authentication through GET /media/{id}/file. Media stays private.

MCP upload and download tools return a resource URL, a 15-minute ticket, the required header and HTTP instructions. Send bytes through HTTP rather than embedding them in model arguments.

A ticket works only for its specified resource. It stops working if the integration is revoked or loses account access. Upload tickets also stop working after completion.

Follow the returned instructions. Keep private ticket URLs and tokens out of public logs.