Upload local files

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

Call Upload files (POST /uploads) 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.
PUT the raw file bytes to the returned upload URL using the returned method and required headers. Do not send multipart form data.
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. See Create a brand.
Image in a Brand Library	Pass `uploadId` and `brandSessionId` to POST /images/uploads. 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 for the public capability map.

Getting started

Guides

Use cases

MCP

Upload local files

Stage the file

Choose a REST destination

Choose an MCP destination

​Stage the file

​Choose a REST destination

​Choose an MCP destination

Stage the file

Choose a REST destination

Choose an MCP destination