---
title: "Upload an attachment"
canonical: "https://bird.com/docs/api/reference/create-amb-attachment"
---

# Upload an attachment

`POST /v1/amb/attachments`

Uploads a file to Apple for the business account identified by `from`
and returns an attachment you can send by `attachment_id`. Send the file
as `multipart/form-data` with `from` and `file`, at most 25,000,000 bytes;
or supply `from` and an HTTPS `source_url`, which Bird downloads, at most
99,999,999 bytes, as JSON or as multipart form fields. Bird encrypts and
uploads the file to Apple before it responds.

The name is `name`, else the uploaded filename, else the last segment of
the `source_url` path. The media type is `mime_type`, else the declared
type of the uploaded file part, else the type Bird detects from the
contents.

Each request uploads a new attachment, even for a file you uploaded
before; retry with the same `Idempotency-Key` to receive the first
result. `expires_at` is Bird's estimate of when Apple stops holding the
attachment, 30 days after the upload or the last message that used it.
An unknown `from` returns `404`; a disconnected business account
returns `422`.

## Servers

- `https://{region}.platform.bird.com`: Regional API endpoint. Use the host for the region your organization is hosted in. Official Bird SDKs and the CLI select it automatically from your API key, so you rarely need to set it by hand.
  - `region`: `us1`, `eu1`. Default: `us1`. The region your organization's data is hosted in.
- `https://platform.bird.com`: Region-independent endpoint for authentication and account administration.
- `http://localhost:8080`: Local development.

## Authentication

Use one authentication option:

- `BearerAuth`: HTTP bearer authentication. Pass the API key as a bearer token in the `Authorization` header. Workspace
keys use `bk_{region}_*`; organization master keys use `bm_{region}_*`.
The prefix identifies the region and selects the
API endpoint. Official Bird SDKs and the CLI derive the region from the key.

- `CookieAuth`: Send `bird_session` in cookie. Session cookie set after signing in to the Bird dashboard. The cookie
value is an opaque session token; no session data is stored in the cookie
itself.

## Code samples

**CLI**

```sh
bird amb attachments upload --from <from> --file ./document.pdf
```

Examples: [CLI](/docs/api/reference/create-amb-attachment.cli.md) · [MCP](/docs/api/reference/create-amb-attachment.mcp.md) · [cURL](/docs/api/reference/create-amb-attachment.curl.md)

## Example response `201`

```json
{
  "id": "aat_01krdgeqcxet5s7t44vh8rt9mg",
  "business_account_id": "abz_01krdgeqcxet5s7t44vh8rt9mg",
  "origin": "received",
  "message_id": "amb_01krdgeqcxet5s7t44vh8rt9mg",
  "name": "receipt.pdf",
  "mime_type": "application/pdf"
}
```

## Header parameters

- `X-Workspace-Id` (string, optional): 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.
- `Idempotency-Key` (string, required): Required client-supplied deduplication key for this write. Reuse it for retries of the same intent. Successful results replay within the configured idempotency window (three hours by default); selected connected-app writes also replay uncertain-write conflicts. Use a new key only after confirming the prior result and beginning a different action.
- `X-Organization-Id` (string, optional): 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

- `from` (string, required): Apple business identifier of the business account that sends the attachment. Read it from the business account's apple_business_id. Only this business account can send the attachment.
- `source_url` (string, required): HTTPS URL of the file, at most 99,999,999 bytes. Bird downloads it and uploads it to Apple. A non-HTTPS URL is refused with a `422` `AMBEndpointNotHTTPS`.
- `name` (string): Display filename. Defaults to the last segment of the source_url path.
- `mime_type` (string): Media type of the file. Defaults to the type Bird detects from the contents.

## Response body

- `id` (string, required): Send it as `attachment_id`.
- `business_account_id` (string, required): The business account Apple holds the attachment for.
- `origin` (string, required)

  How Bird obtained an attachment:

  - `received`: A customer sent it in a message.
  - `sent`: You sent it in a message by `source_url`.
  - `uploaded`: You uploaded it with createAMBAttachment.

  Possible values: `received`, `sent`, `uploaded`
- `message_id` (string): The message the attachment belongs to.
- `name` (string, required): Display filename. May be empty for an attachment stored before this release.
- `mime_type` (string, required): Media type of the attachment. May be empty for an attachment stored before this release.
- `size` (integer, required): Attachment size in bytes. May be 0 for an attachment stored before this release.
- `expires_at` (string, required): Bird's estimate of when Apple stops holding the attachment, 30 days after it was received, uploaded or last sent. A send within 24 hours of this time is refused.
- `created_at` (string, required): When Bird stored the attachment.

## 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)