POST /v1/content/add-image takes a public image URL. A file on your machine
takes three free calls, because a JSON request body can’t carry a file that
size. Open an upload, POST the raw bytes to the URL it returns, then add the
image with its uploadId.
What You Can Upload
Open an Upload
Name the file, its type, and its size in bytes (wc -c < logo.png prints it).
201:
contentType or a size over the cap is 400 INVALID_REQUEST.
With 20 uploads already open, the brand gets 429 RATE_LIMITED, and
Retry-After is when the oldest one expires. An organization key names the
brand with X-Brand-Id here and on the last call, as on every brand-scoped
route.
Send the File
POST the raw bytes touploadUrl before expiresAt. Send no Authorization
header. The URL carries its own credential, so keep it as private as an API
key.
200 with { uploadId, status: "uploaded", size, expiresAt }. The
new expiresAt is 15 minutes after the bytes landed, and it is your deadline
for the next call. Sending again never replaces the first file.
Add It to the Library
200 with the image, now in the brand library and on
Assets:
contentType that differs is
ignored. fileName names the converted file, and the image’s description in
the library comes from its caption. Use assetId to find the image in
GET /v1/brand/images or to remove it with DELETE /v1/brand/images/{assetId}.
A repeat with the same uploadId returns the same answer for 24 hours, even
if the image was deleted since. A retry after a timeout is safe.
All Three Steps in One Call
The TypeScript SDK’sbrew.content.uploadImage opens the upload, sends the
bytes, and adds the image:
contentType is optional here; the file name’s extension gives it. Before
sending anything it refuses an empty file, a file over 20 MB, or an SVG over
2 MB with a TypeError. It does not retry opening the upload (a retry after a
lost answer would hold a second of the 20 slots), so if that step fails, call
uploadImage again. The other answers and errors are the ones above.
Recover a Lost Final Answer
These recovery fields need TypeScript SDK 13.4.0 or later. On 13.3.0 or
earlier, use the explicit steps above and keep the upload ID yourself.
addImage call loses its answer, its transport error exposes the
original uploadId and idempotencyKey. Replay only that step with the
same brand client you used for uploadImage:
error.inProgress is true, this example rethrows instead of replaying
immediately. Save the upload ID and key with that job, wait, then call
addImage on the same brand client. API and parse errors expose the fields
too; inspect the API code or report the parse error before deciding to replay.
Calling uploadImage() again opens a new upload, even with the same file
and key. Reusing that key with a different { uploadId } body correctly
returns 409 IDEMPOTENCY_CONFLICT. See Idempotency.
Use the original ID and key with addImage instead.
The completed result replays for 24 hours, as described in
Add It to the Library. An exposed ID does not
prove the image was saved. If finalization did not complete, the upload
can still expire or return one of the errors above.
Failures while opening the upload or sending its bytes leave uploadId
undefined. The SDK exposes the ID only after the helper returns an error.
For recovery after cancellation or a process exit before you save that
state, use the explicit steps above and retain the upload ID and your
chosen final key. Caller aborts still return the signal’s original
reason without adding recovery fields.
From the CLI
--json for the raw answer). To drive the steps yourself, run
brew-cli content create-image-upload --file-name logo.png --size 48213, then
the curl it prints, then brew-cli content add-image --upload-id <uploadId>.
brew-cli brand delete-image <assetId> removes an image (it asks first; pass
--yes in scripts).
From CLI 0.19.0, errors from a finalization request include its
original uploadId and idempotencyKey. If the outcome is unknown, the
error also includes a retryCommand that runs content add-image with
those values and the original brand and API target. This works after a
final-step connection failure, timeout or interruption. Run the returned
command to recover; repeating content upload-image opens a new upload.
Wait before running the command if the error says finalization is still
in progress. A definite API refusal keeps its original guidance without
a replay command. Failures before finalization do not provide a
finalization recovery record. The command reuses your configured
authentication and does not include credentials in its text.
From MCP
Over MCP the flow iscreate_image_upload, the bytes to uploadUrl, then
add_image with the uploadId. Sending the bytes takes a client with a shell
or an HTTP tool on the file’s machine, such as Claude Code or Cursor. A
chat-only client should ask for a public link and call add_image with
imageUrl (see Assets).
Related
- Assets: find, add, and delete images in the app and from an agent.
POST /v1/content/image-uploadsandPOST /v1/content/add-imagein the Public API v1 reference (sidebar): full schemas.- Rate limits: the 20 open uploads.
- Errors: every code above.
Need Help?
Our team is ready to support you at every step of your journey with Brew. Choose the option that works best for you:- Self-Service Tools
- Talk to Our Team
Search Documentation
Type in the “Ask any question” search bar at the top left to instantly find relevant documentation pages.
Ask ChatGPT or Claude
Click here to open the Copy page menu at the top of this page, then send the page to ChatGPT, Claude, or your editor.