---
title: "Manage media-library files"
description: "Upload files to public URLs, organize assets in folders, inspect permitted references, and remove library entries through Bird's API, CLI, and MCP."
canonical: "https://bird.com/docs/guides/media-library"
---

# 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`. See [API authentication](/docs/api/authentication) and [CLI setup](/docs/cli).

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 retain their bytes; file-type recognition is not a malware scan.

## Upload a file

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

The response includes the asset's `id` and `url`. `--file -` reads stdin. Images accept PNG, JPEG, GIF, and WebP up to 5 MiB; video, audio, and PDF accept the formats and 25 MB limit listed in the [upload reference](/docs/api/reference/create-asset).

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.

Identical file bytes return the existing asset unchanged, including its name and folder. To change metadata, update that asset. To replace file contents, upload a new file and use its new URL.

## Find and organize assets

```sh
bird assets list --kind image
bird assets folders create --name "Campaign images"
```

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

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

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.

Each workspace supports 1,000 active folders and 10,000 retained folders, including deleted folders. Deletion frees an active slot but does not release retained capacity. At the retained limit, reuse existing folders or the library root; this limit is fixed, but you can contact support to discuss your use case.

To move an asset back to the root, send `{"folder_id":null}` to the [update endpoint](/docs/api/reference/update-asset), or provide that JSON with the CLI's `--body-file`. `{"alt_text":null}` clears alternative text. Omitted fields remain unchanged.

## Inspect usage and remove entries

```sh
bird assets references list ast_01krdgeqcxet5s7t44vh8rt9mg
```

References include saved content you have permission to read. They exclude unsaved edits and older published versions. A response with `truncated: true` is incomplete; an empty response does not prove the URL is unused outside Bird.

```sh
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. 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.

## Use MCP or an SDK

Local MCP exposes `assets_upload` for file uploads. Use a local file path for files larger than the inline limit. Hosted MCP supports the ten metadata, folder, and reference tools; it does not expose file upload. See [MCP setup](/docs/ai/mcp-server).

The Go, TypeScript, Python, and PHP SDKs expose `assets`, nested `folders`, and `references` resources for the ten JSON operations. Upload through HTTP or the CLI, then use the returned asset ID with your SDK.

## Resolve upload errors

A size error requires a smaller file; changing its extension does not change the recognized type. A byte-quota error requires available organization storage. The organization also has a 100,000 retained-asset limit per region; removed library entries still count, so reuse existing assets where possible. A duplicate multipart field is rejected: send each field once. For a temporary busy response, retry with the same idempotency key. Error responses link to code-specific recovery instructions.

## Next steps

- [Browse the asset API](/docs/api/reference/list-assets).
- [Browse the folder API](/docs/api/reference/list-asset-folders).
- [Set up MCP](/docs/ai/mcp-server).

## Related resources

- [Should I use a Bird SDK or call the API directly?](/explained/platform/should-i-use-an-sdk-or-call-the-api-directly) (answer)
- [Build your first integration](/learn/paths/integration) (course)
- [Send your first email](/docs/get-started/send-your-first-email) (docs)

[Get an implementation brief](/learn/workspace?topic=api-basics)