assets

Update asset metadata or folder placement

Renames an asset, sets its default alternative text, or moves it to a folder. These changes preserve the asset's URL and bytes.

patch/v1/assets/{asset_id}

Request

  • Base URL: https://us1.platform.bird.com
  • URL: https://us1.platform.bird.com/v1/assets/{asset_id}
  • Auth: one of:
    • HTTP bearer
    • API key in cookie bird_session

Path parameters

asset_idstring required
Example:ast_01krdgeqcxet5s7t44vh8rt9mg

ID of the asset.

Headers

Idempotency-Keystring

Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay.

On a supported operation, if idempotency protection is unavailable before execution, the API returns 503 IdempotencyUnavailable (E01033) without executing this attempt. Retry with backoff using the same key and request. An operation that takes effect before its response is retained can still execute again on retry.

Two distinct 409 errors signal misuse:

  • request_in_progress (E01004): The same key is currently being processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.
  • idempotency_key_reuse (E01005): The same key has already completed against a different request body or method. Generate a new key.

Recommended key format is <event-type>/<entity-id> (for example welcome-user/usr_abc123).

X-Workspace-Idstring

Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.

X-Organization-Idstring

Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.

Request body

namestring

The asset's display name.

alt_textstring nullable

Default alternative text describing the image. Send null to clear it.

folder_idstring

Example request

{
  "name": "Summer banner",
  "alt_text": "Sunset over the ocean"
}

Response

The updated asset.

created_atstring date-time required
updated_atstring date-time required
idstring required
urlstring uri 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_urlstring uri nullable 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.

namestring required

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

content_typestring required

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

kindstring 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.
size_bytesinteger 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.

widthinteger nullable required

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

heightinteger nullable required

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

alt_textstring nullable required

Default alternative text describing the asset, carried along whenever it is placed. Most mail clients block images by default, so for an image this is often the only thing a recipient reads.

folder_idstring required
deleted_atstring date-time nullable 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.

Example response

{
  "created_at": "2026-05-20T09:14:52Z",
  "updated_at": "2026-05-25T16:42:01Z",
  "id": "ast_01krdgeqcxet5s7t44vh8rt9mg",
  "kind": "image",
  "folder_id": "asf_01krdgeqcxet5s7t44vh8rt9mg"
}

Changes

No recorded changes to this operation across all 2 revisions of this API.