Manage media-library files

Upload media once and reuse its public URL in your content. The API, bird assets commands, and MCP tools manage the same workspace library as the dashboard.

Before you start

Use a workspace API key with assets:write for uploads and changes, and assets:read for reads. To see email-template references, also grant email_management:read. Use the API host for your workspace's region: https://eu1.platform.bird.com for EU keys or https://us1.platform.bird.com for US keys. The CLI and SDKs select the host from your key. See API authentication and CLI setup.

Uploaded URLs are accessible without authentication. Only upload files intended for public access. Images are re-encoded to remove embedded metadata. PDF, audio, and video pass container-structure checks and retain their bytes. These checks do not scan for malware or remove embedded content. A file can be rejected for excessive processing complexity even when it is below the file-size limit.

Upload a file

bird assets upload --file ./banner.png --name "Summer banner" --alt-text "Summer collection"

The response includes the asset's id and public url. Use url when embedding an image in your editor or linking to a file. thumbnail_url is an image preview for your picker; it is null for audio, video, and documents. PDFs are served as downloads. --file - reads stdin. See the upload reference for supported formats and file-size limits.

For HTTP, send multipart/form-data with one required file part. Optional parts are name, alt_text, and folder_id. Include each part at most once and retain the same Idempotency-Key when retrying an upload.

Set BIRD_API_KEY to your workspace key and BIRD_API_URL to its regional host. With cURL and uuidgen installed, upload a file:

UPLOAD_IDEMPOTENCY_KEY="$(uuidgen)"
curl --fail-with-body "$BIRD_API_URL/v1/assets" \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Idempotency-Key: $UPLOAD_IDEMPOTENCY_KEY" \
  -F "file=@./banner.png" \
  -F "name=Summer banner" \
  -F "alt_text=Summer collection"

Let cURL set the multipart Content-Type and boundary. Keep UPLOAD_IDEMPOTENCY_KEY and the request unchanged when retrying; generate a new key for a different upload. The CLI accepts the same key with --idempotency-key.

A new upload returns 201 Created. Identical file bytes matching an active asset in the same workspace return that asset with 200 OK, preserving its name, alternative text, and folder. If you supply folder_id, it must identify an existing folder even for a duplicate. To change metadata, update the asset. To replace file contents, upload a new file and use its new URL. Uploading the same bytes after deleting the library entry creates a new asset and URL.

Find and organize assets

bird assets list --kind image --q "banner"
bird assets folders create --name "Campaign images"

Use the returned IDs to retrieve an asset or move it:

bird assets get ast_01krdgeqcxet5s7t44vh8rt9mg
bird assets update ast_01krdgeqcxet5s7t44vh8rt9mg --folder-id asf_01krdgeqcxet5s7t44vh8rt9mg

Asset lists are paginated. Use --folder-id for one folder or --root-only for unfiled assets; these filters cannot be combined. Follow the pagination contract to retrieve subsequent pages.

Moving files or folders preserves asset URLs. Folder lists are flat and paginated; read every page before assembling a complete tree from parent_id. A folder filter matches only files directly inside that folder.

Folder names are unique within their parent, ignoring case. The folder reference lists the depth, active-folder, and retained-folder limits. Deletion frees an active slot but does not release retained capacity. At the retained limit, reuse existing folders or the library root.

To move an asset back to the root, send {"folder_id":null} to the update endpoint, or provide that JSON with the CLI's --body-file. {"alt_text":null} clears alternative text. Omitted fields remain unchanged. Updating an asset's default alternative text does not change descriptions already copied into saved content.

Inspect usage and remove entries

bird assets references list ast_01krdgeqcxet5s7t44vh8rt9mg

References currently report email templates you have permission to read, with usage identifying saved draft, published, or both versions. They exclude unsaved edits and older published versions. Without email_management:read, email-template references are omitted. A response with truncated: true is incomplete; an empty response does not prove the asset is unused. It may be referenced by other content or outside Bird.

bird assets delete ast_01krdgeqcxet5s7t44vh8rt9mg --yes

Deleting an asset removes its library entry. Its public URL continues to serve the file, including in content you already sent. To find a removed entry, use bird assets list --deleted only or retrieve it by ID. Removed entries cannot be updated; re-upload the file to create a new entry.

Deleting a folder moves its contents to the parent. If a child folder name conflicts at the destination, deletion is refused; rename or move the conflicting child folder, then retry. Neither operation is an emergency takedown. If a public file needs removal for a security or abuse issue, contact support with its asset ID and public URL. A takedown can make the URL unavailable; it cannot revoke copies someone has already downloaded.

Use MCP or an SDK

Local MCP (bird mcp) exposes assets_upload with a required file argument containing a local path or a data: URI. Inline files are limited to 64 KiB decoded; use a local path for larger files. Paths refer to the machine running bird mcp. Optional name, alt_text, and folder_id arguments match the upload API. Hosted MCP exposes metadata, folder, and reference tools. Upload sessions use assets_uploads_create to create or recover an intent. Check the returned state and next steps: a completed replay already has its result, and a pending replay may omit upload during the 30-second instruction cooldown. When upload is present, the client sends the original bytes from its code environment to that temporary URL, then assets_uploads_complete publishes the asset. Status, refresh and cancellation use assets_uploads_get, assets_uploads_prepare and assets_uploads_cancel. The client must be able to read the original file and make the HTTPS transfer; a chat attachment alone does not guarantee those capabilities. File bytes stay outside MCP arguments. See MCP setup.

The Go, TypeScript, Python, and PHP SDKs expose assets, nested folders, and references resources for library management. The nested uploads resource provides typed methods for the five upload-session operations described above. It does not send the file bytes: your application performs the HTTPS transfer before completing the session. Direct multipart upload remains available through HTTP or the CLI. The asset reference includes SDK examples for library operations.

Resolve upload errors

• Unsupported or invalid file: export the file in a supported format and confirm it is undamaged. Renaming its extension does not change its type. For complex images or containers, resize, simplify, or re-export the file before retrying.
• File too large: compress or shorten the file to fit the upload limits. Images must fit before and after re-encoding.
• Storage quota reached: check the quota named in the error. Removing an entry releases active-byte usage, but its bytes remain in stored-byte usage. Workspace ceilings can also apply. Ask an organization administrator to review the relevant quota; deleting more entries does not free stored capacity.
• Retained-asset limit reached: removed entries still count toward the regional organization limit. Reuse active assets where possible.
• Duplicate multipart field: send each field once.
• Temporary busy response: wait briefly, then retry the unchanged request with the same idempotency key. See idempotency for retry and retained-error behavior.

Error responses include code-specific recovery instructions.

Next steps

• Browse the asset API.
• Browse the folder API.
• Set up MCP.