Sign inGet Started
Get started
Guides
API Reference
SDKs
CLI
Knowledge Base
Changelog

Create a media-library asset

POST
/v1/assets
bird assets upload --file ./document.pdf
Response200
{
  "id": "ast_01krdgeqcxet5s7t44vh8rt9mg",
  "url": "https://us1.assets.birdusercontent.com/6fcy8y6a483sewgnjk2g35y2qz/01krdgeqcxet5s7t44vh8rt9mg/document.pdf",
  "thumbnail_url": null,
  "name": "document.pdf",
  "content_type": "application/pdf",
  "kind": "document",
  "size_bytes": 48210,
  "width": null,
  "height": null,
  "alt_text": null,
  "folder_id": null,
  "deleted_at": null,
  "created_at": "2026-05-20T09:14:52Z",
  "updated_at": "2026-05-20T09:14:52Z"
}

Uploads a file to the workspace's media library and returns its permanent public URL. Send a multipart/form-data body with the bytes in the file part.

The file's contents determine its type, and the type determines its kind:

KindAccepted formatsMaximum size
imagePNG, JPEG, GIF, static WebP5 MiB (5,242,880 bytes)
videoMP4, WebM, QuickTime25 MB
audioMP3, M4A, Ogg, WAV25 MB
documentPDF25 MB

Images are re-encoded to remove embedded metadata and apply recorded rotation. Animated GIFs keep their animation, and static WebP images become JPEG or PNG. Animated WebP is not supported. Other files pass container-structure validation and are stored byte-for-byte. Validation does not scan for malware. Files that exceed image-processing or container-complexity limits can be rejected even below the byte limit. Documents are downloads; other media displays inline. Asset bytes and URLs do not change. Upload new content as a new asset. A duplicate file in the same workspace returns the existing active asset with 200 OK; a new asset returns 201 Created. Uploading the same bytes after removing the library entry creates a new asset and URL. An organization can retain at most 100,000 assets per region, including removed library entries whose URLs still serve. Reusing an existing asset does not use another slot.

Include each multipart field at most once. file is required. Optional name is a display name of up to 255 characters and defaults to the filename when omitted or empty after trimming; alt_text allows up to 1,000 characters; folder_id places a new asset in an existing folder. Omit folder_id for the library root. Each text part is limited to 8 KiB before trimming surrounding whitespace. Duplicate uploads retain the existing asset's metadata and folder.

See Manage media-library files for HTTP upload examples, CLI and MCP use, and storage-quota guidance.

Response Payload

created_at
string
required
updated_at
string
required
id
string
required
url
string
required

The asset's permanent public URL. Safe to embed or link in sent messages; for a document the usable form is a link.

thumbnail_url
nullable string
required

A small preview of the asset, for rendering a picker or a grid. Intended for your own interfaces rather than for embedding in messages. Null for every kind but image: generating a preview of a video, an audio file, or a document would mean rendering its contents, which the library does not do. Show an icon for the kind instead.

name
string
required

The asset's display name. Defaults to the uploaded file's name.

content_type
string
required

The stored file's media type, determined from its contents.

kind
string
required

The category a media-library asset's type falls into. Use it to group or filter a mixed library.

  • image: covers PNG, JPEG, and GIF.
  • video: covers MP4, WebM, and QuickTime.
  • audio: covers MP3, M4A, Ogg, and WAV.
  • document: covers PDF.

Possible values (may grow over time): image, video, audio, document

size_bytes
integer
required

The stored file's size in bytes. Images are re-encoded on upload, so for those this can differ from the size of the file you sent. Every other kind is stored byte-for-byte.

width
nullable integer
required

The stored image's width in pixels. Null for every kind but image.

height
nullable integer
required

The stored image's height in pixels. Null for every kind but image.

alt_text
nullable string
required

Default alternative text for the asset. Use it as the starting point for an image description when inserting the asset into content. Updating this field does not update descriptions already copied into saved content.

folder_id
nullable string
required

The folder the asset is filed in, or null when it sits at the top level of the library. Filing an asset never changes its URL.

deleted_at
nullable string
required

When the asset was removed from the library, or null if it is still listed. A removed asset keeps serving at its original URL.

Related resources

Continue with the documentation, guides and examples for this topic.

Get an implementation brief