# Bloom

> Documentation for Bloom — the brand layer for agents, software and marketers.

## Docs

- [Get account](https://www.trybloom.ai/docs/api-reference/account/get-account.md): Return basic profile information for the authenticated API key owner. Useful as a whoami probe to verify which account a key belongs to.
- [Get credit balance](https://www.trybloom.ai/docs/api-reference/account/get-credit-balance.md): Check the remaining credit balance for a workspace. Defaults to the caller's personal workspace; pass `workspaceId` to query a team workspace's balance.
- [List workspaces](https://www.trybloom.ai/docs/api-reference/account/list-workspaces.md): List workspaces the caller can access. Always includes the Personal workspace (id: null) first, followed by team workspaces.
- [Create a brand](https://www.trybloom.ai/docs/api-reference/brands/create-a-brand.md): Start brand onboarding for a website or Instagram profile URL. Extracts branding and starts visual DNA analysis. Returns immediately with the brand ID. Poll GET /brands/{id} until status is "ready". Defaults to the caller's personal workspace; pass `workspaceId` to onboard into a team workspace.
- [Get a brand](https://www.trybloom.ai/docs/api-reference/brands/get-a-brand.md): Get a brand by ID. Use this to poll for onboarding completion. When status is "ready", the brand can generate images. If status is "logo_required", provide a logo via PUT /brands/{id}/logo. Use wait=true to hold the connection until a terminal status is reached.
- [List brands](https://www.trybloom.ai/docs/api-reference/brands/list-brands.md): List brand sessions with cursor-based pagination. Use the returned IDs as brandSessionId when generating images.
- [Update brand logo (file)](https://www.trybloom.ai/docs/api-reference/brands/update-brand-logo-file.md): Update the logo for a brand by uploading raw bytes (multipart/form-data). Use this when the logo is local — for remote URLs, use PUT /brands/{id}/logo. Validates and processes the file (SVG and AVIF are converted to PNG; transparency gets an optimal background), then starts (or restarts) visual DNA…
- [Update brand logo (signed)](https://www.trybloom.ai/docs/api-reference/brands/update-brand-logo-signed.md): Update the logo for a brand by uploading raw bytes (multipart/form-data) using a short-lived, single-use token minted via the bloom_create_logo_upload_url MCP tool. The token in the path is the credential — no Authorization header is expected. Same validation/storage pipeline as PUT /brands/{id}/log…
- [Update brand logo (url)](https://www.trybloom.ai/docs/api-reference/brands/update-brand-logo-url.md): Update the logo for a brand session. Downloads and validates the logo, then starts (or restarts) visual DNA extraction and returns status "analyzing". For image-based onboarding the stitched collage is preserved as the visual identity, so no extraction runs and status "ready" is returned. Common whe…
- [Edit an image](https://www.trybloom.ai/docs/api-reference/images/edit-an-image.md): Edit a previously generated or uploaded image. The prompt describes what to change. Aspect ratio is locked to the original image's ratio. Optionally include referenceImageIds for additional context. Returns immediately with a new image ID. Poll GET /images/{id} to check status and retrieve the resul…
- [Generate an image](https://www.trybloom.ai/docs/api-reference/images/generate-an-image.md): Start an image generation. Returns immediately with the image ID(s). Poll GET /images/{id} to check status and retrieve the result. Optionally include referenceImageIds for style/content guidance.
- [Get an image](https://www.trybloom.ai/docs/api-reference/images/get-an-image.md): Get an image by ID. Use this to poll for generation results. When status is "completed", imageUrl contains a short redirect URL (/img/{id}). Use wait=true to hold the connection until a terminal status is reached.
- [List images](https://www.trybloom.ai/docs/api-reference/images/list-images.md): List images scoped to a brand or across all brands, with cursor-based pagination. Supports filtering by status and action type. Returns short redirect URLs (/img/{id}) for completed images by default. When `ids` is provided, pass `wait=true` to hold the connection until every referenced image reache…
- [Resize an image](https://www.trybloom.ai/docs/api-reference/images/resize-an-image.md): Resize a completed image to a different aspect ratio. Returns immediately with a new image ID. Poll GET /images/{id} to check status and retrieve the result.
- [Semantic Search](https://www.trybloom.ai/docs/api-reference/images/semantic-search.md): Semantic search (powered by vector embeddings) over the brand session's library images, ranked nearest-first. Library images are those whose `source` is `uploaded` (added by the user) or `scraped` (pulled in during onboarding) — generated images are excluded. Pass `cursor` from the previous response…
- [Upload an image (file)](https://www.trybloom.ai/docs/api-reference/images/upload-an-image-file.md): Upload raw image bytes (multipart/form-data) for use as a reference or edit subject. Use this when the image is local — for remote URLs, use POST /images/uploads. Returns an image ID and URL usable with the generate or edit endpoints.
- [Upload an image (signed)](https://www.trybloom.ai/docs/api-reference/images/upload-an-image-signed.md): Upload raw image bytes (multipart/form-data) using a short-lived, single-use token minted via the bloom_create_image_upload_url MCP tool. The token in the path is the credential — no Authorization header is expected. Same validation/storage pipeline as POST /images/uploads/file. Returns an image ID…
- [Upload an image (url)](https://www.trybloom.ai/docs/api-reference/images/upload-an-image-url.md): Upload an image by URL for use as a reference or edit subject. The server downloads, validates, and stores the image. Returns the image ID for use with the generate or edit endpoints via referenceImageIds, or as an edit subject via POST /images/{id}/edit.
- [Authentication](https://www.trybloom.ai/docs/api/authentication.md): How to authenticate requests to the Bloom API.
- [Automation](https://www.trybloom.ai/docs/api/guides/automation.md): Wire Bloom into Zapier, n8n, Make, Gumloop, or any other workflow tool.
- [Getting Started](https://www.trybloom.ai/docs/api/index.md): Make your first brand-aware image generation in four steps.
- [OpenAPI](https://www.trybloom.ai/docs/api/openapi.md): OpenAPI v3.1 spec for the Bloom REST API.
- [Usage Limits](https://www.trybloom.ai/docs/api/usage-limits.md): Credits, rate limits, and plan tiers for the Bloom API.

## OpenAPI Specs

- [spec](https://www.trybloom.ai/api/v1/spec.json)