> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trybloom.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Upload local files

> Stage a local file, then use it as Brand evidence, a Library image, a logo, or a font.

Local files use one shared upload flow: reserve temporary storage, PUT the file's bytes, then pass its upload ID to the operation that will use it. That last operation determines whether the file becomes Brand evidence, a Library image, or a font asset. Selecting an image as a logo or assigning a font to Heading or Body requires a further profile update.

If your file already has a public URL, pass the URL directly to a supported consuming operation and skip staging.

## Stage the file

1. Call [Upload files (`POST /uploads`)](/api-reference/uploads/upload-files) in REST or `bloom_create_upload_urls` in MCP to reserve temporary storage and receive upload instructions. Use the workspace where the file will be consumed.
2. PUT the raw file bytes to the returned upload URL using the returned method and required headers. Do not send multipart form data.
3. After the PUT succeeds, pass `uploadId` in REST or `upload_id` in MCP to the destination below before the upload expires. There is no separate confirmation request.

`POST /uploads` accepts 1–30 files, up to 100 MiB per file and 256 MiB combined. It returns `uploadId`, `uploadUrl`, `method`, required headers, and `expiresAt` for each file. The destination applies its own validation, so a successful PUT does not mean the file has been accepted there.

Temporary uploads are private and belong to one workspace. Authorized operations in that workspace can reuse an upload until it expires. Staging alone creates no Brand source, Library image, font asset, or logo.

For an existing Brand, use its workspace when reserving the upload. For a new Brand, use the same workspace for staging and onboarding. In MCP, read an existing Brand's `workspace_id` with `list_brands` or `get_brand`; omit it only when staging and consumption both use the personal workspace.

## Choose a REST destination

The public REST API supports these destinations:

| Destination                     | After the PUT succeeds                                                                                                                                                                                                             |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Source evidence for a new Brand | Include `{ "kind": "file", "uploadId": "..." }` in `sources` when calling [POST /brands](/api-reference/brands/create-a-brand). See [Create a brand](/guides/create-brand).                                                        |
| Image in a Brand Library        | Pass `uploadId` and `brandSessionId` to [POST /images/uploads](/api-reference/images/add-an-image-to-a-brand-library). Bloom validates the image, reuses an exact match or stores a new image, and returns the canonical image ID. |

The existing-Brand source, logo, and font workflows below depend on account-specific MCP capabilities. They are not part of the public REST reference.

## Choose an MCP destination

After staging with `bloom_create_upload_urls` and completing the PUT, use the matching public tool:

| Destination                     | Consuming tool and follow-up                                    |
| ------------------------------- | --------------------------------------------------------------- |
| Source evidence for a new Brand | Pass the `upload_id` as a file source to `bloom_onboard_brand`. |
| Image in a Brand Library        | Pass the `upload_id` to `bloom_upload_image`.                   |

Other destinations require Brand editing or profile capabilities available to the connected account:

| Destination                           | Required workflow                                                                                                                                                                                                                                                              |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Source evidence for an existing Brand | Submit the staged file through the available Brand editing workflow, review the proposed edit, then apply it.                                                                                                                                                                  |
| Primary logo                          | For a local PNG, JPEG, WebP, or AVIF file, save it to the Brand Library with `bloom_upload_image`, then assign that Library image as the primary logo through the available profile workflow. An SVG or GIF logo must already exist in the Brand Library before you assign it. |
| Custom Heading or Body font           | Validate the staged font and create a font asset through the available font workflow, then assign that asset to Heading or Body through the typography profile workflow.                                                                                                       |

Read the connected account's live `tools/list` before constructing requests. Its schemas define which capabilities are available and the exact sequence and fields for each workflow. See [Available tools](/mcp/tools) for the public capability map.