# Bloom

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

- [Introduction](https://docs.trybloom.ai/introduction.md): What Bloom provides and where to start.
- [How Bloom works](https://docs.trybloom.ai/how-bloom-works.md): How source evidence becomes brand context that software and agents can call.
- [API quickstart](https://docs.trybloom.ai/api/index.md): Make your first call to Bloom in five steps.
- [MCP quickstart](https://docs.trybloom.ai/mcp/getting-started.md): Add Bloom guidance, connect your agent, and generate your first on-brand image.
- [Create a brand](https://docs.trybloom.ai/guides/create-brand.md): Turn websites, Instagram accounts, files, and instructions into a ready brand.
- [Retrieve and use a Brand Skill](https://docs.trybloom.ai/guides/use-brand-skill.md): Read one brand's complete active Skill from a server-side integration.
- [Generate images](https://docs.trybloom.ai/guides/generate-images.md): Generate brand-aware images through the API or an MCP-connected agent.
- [Edit and adapt images](https://docs.trybloom.ai/guides/edit-adapt-images.md): Edit, resize, remove backgrounds from, and vectorize existing images.
- [Connect Bloom](https://docs.trybloom.ai/mcp/connect.md): Connect each agent to Bloom MCP — sign in with Bloom, or use a static API key.
- [Available tools](https://docs.trybloom.ai/mcp/tools.md): Generally available Bloom MCP capabilities and their roles.
- [Troubleshooting](https://docs.trybloom.ai/mcp/troubleshooting.md): Diagnose Bloom MCP connection, validation, lifecycle, billing, and rate-limit failures.
- [API overview](https://docs.trybloom.ai/api/openapi.md): The complete public REST contract and its live OpenAPI specification.
- [Authentication](https://docs.trybloom.ai/api/authentication.md): How to authenticate requests to the Bloom API.
- [Credits and limits](https://docs.trybloom.ai/api/usage-limits.md): Credits, rate limits, and plan behavior shared by the Bloom API and MCP.
- [Get account](https://docs.trybloom.ai/api-reference/account/get-account.md): Return basic profile information for the authenticated user. Use it as a `whoami` check to verify which account the credentials belong to.
- [Get credit balance](https://docs.trybloom.ai/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://docs.trybloom.ai/api-reference/account/list-workspaces.md): List the workspaces the caller can access. The personal workspace (`is_personal: true`) appears first and is the default for create operations; omit `workspaceId` to use it. This endpoint always returns all accessible workspaces.
- [List brands](https://docs.trybloom.ai/api-reference/brands/list-brands.md): List brand sessions with cursor-based pagination. Use a returned ID as `brandSessionId` when generating images.
- [Create a brand](https://docs.trybloom.ai/api-reference/brands/create-a-brand.md): Queue Brand creation from either the single website/Instagram `url` input retained for existing integrations or an ordered `sources` array containing a website, Instagram account, and files. Both inputs build a Brand Skill unless `logoUrl` is supplied with `url`; that explicit-logo compatibility opt…
- [Get a brand](https://docs.trybloom.ai/api-reference/brands/get-a-brand.md): Get a brand by ID. When `status` is `ready`, the brand can generate images. If `status` is `logo_required`, provide a logo with `PUT /brands/{id}/logo`. A brand with `status` `failed` includes failure details safe to show to users. Use `wait=true` to hold the connection until the status is `ready`,…
- [Delete a brand](https://docs.trybloom.ai/api-reference/brands/delete-a-brand.md): Delete a brand by ID. Returns the deleted brand's `id`, `name`, and owning workspace. Deleting the same brand twice returns 404.
- [Inspect a Brand's active Skill](https://docs.trybloom.ai/api-reference/brands/inspect-a-brands-active-skill.md): Return the complete active Brand Skill as one immutable snapshot. The result identifies the exact Skill and includes its safe structured profile, signed custom-font files, every Markdown file, and referenced Brand Library asset IDs. SKILL.md includes the canonical YAML frontmatter stored in the arti…
- [Update brand logo (URL)](https://docs.trybloom.ai/api-reference/brands/update-brand-logo-url.md): Update a brand's logo from a URL. Bloom downloads and validates the logo, starts or restarts visual DNA extraction, and returns `status: "analyzing"`. Use this when `status` is `logo_required` or to replace the logo of a brand with `status` `ready`.
- [Update brand logo (file)](https://docs.trybloom.ai/api-reference/brands/update-brand-logo-file.md): Upload a local logo as raw bytes (`multipart/form-data`). For a remote logo, use `PUT /brands/{id}/logo`. Bloom validates and processes the file, converts SVG and AVIF files to PNG, and adds a suitable background to transparent images. It then starts or restarts visual DNA extraction.
- [Update brand logo (signed)](https://docs.trybloom.ai/api-reference/brands/update-brand-logo-signed.md): Upload a local logo as raw bytes (`multipart/form-data`) using a short-lived, single-use token from the `bloom_create_logo_upload_url` MCP tool. The token in the path is the credential, so no `Authorization` header is expected. This endpoint uses the same validation and storage pipeline as `PUT /bra…
- [List images](https://docs.trybloom.ai/api-reference/images/list-images.md): List images for one brand or across all brands, with cursor-based pagination and filters for status and action type. Returns short redirect URLs such as `/img/{id}` for completed images by default. When you provide `ids`, pass `wait=true` to hold the connection until every referenced image reaches a…
- [Delete images](https://docs.trybloom.ai/api-reference/images/delete-images.md): Delete up to 50 images by ID in one call.
- [Get an image](https://docs.trybloom.ai/api-reference/images/get-an-image.md): Get an image by ID; use this endpoint to poll for generation results. When `status` is `completed`, `imageUrl` contains a short redirect URL such as `/img/{id}`. Use `wait=true` to hold the connection until the image reaches a terminal status. When `status` is `failed` and `failureReason` is `conten…
- [Delete an image](https://docs.trybloom.ai/api-reference/images/delete-an-image.md): Delete a single image by ID (generated, uploaded, or scraped). Returns the deleted image's `id`, `source`, and owning workspace. Deleting the same image twice returns 404.
- [Generate an image](https://docs.trybloom.ai/api-reference/images/generate-an-image.md): Start an image generation and return the image IDs immediately. Poll `GET /images/{id}` to check the status and retrieve the result. Optionally include `referenceImageIds` for style or content guidance.
- [Edit an image](https://docs.trybloom.ai/api-reference/images/edit-an-image.md): Edit a previously generated or uploaded image. Use the prompt to describe what to change. The aspect ratio remains the same as the original image. Optionally include `referenceImageIds` for additional context. The endpoint returns a new image ID immediately; poll `GET /images/{id}` to check the stat…
- [Resize an image](https://docs.trybloom.ai/api-reference/images/resize-an-image.md): Resize a completed image to a different aspect ratio. The endpoint returns a new image ID immediately; poll `GET /images/{id}` to check the status and retrieve the result.
- [Remove the background from an image](https://docs.trybloom.ai/api-reference/images/remove-the-background-from-an-image.md): Remove the background from an image and return a transparent PNG. This works with completed generated images and with uploaded or scraped images. The endpoint returns a new image ID immediately, and the cutout typically completes in under 10 seconds. Poll `GET /images/{id}` to check the status and r…
- [Vectorize an image to SVG](https://docs.trybloom.ai/api-reference/images/vectorize-an-image-to-svg.md): Vectorize a raster image to SVG. This works with completed generated images and with uploaded or scraped images. It works best for logos, icons, and flat artwork; photos give poor results. The endpoint returns a new image ID immediately; poll `GET /images/{id}` to check the status and retrieve the r…
- [Upload an image (URL)](https://docs.trybloom.ai/api-reference/images/upload-an-image-url.md): Upload an image by URL for use as a reference or edit subject. The server downloads and validates the image, then reuses an exact match in the brand session or stores a new one. Returns the canonical image ID and whether it already existed.
- [Upload an image (file)](https://docs.trybloom.ai/api-reference/images/upload-an-image-file.md): Upload a local image as raw bytes (`multipart/form-data`) for use as a reference or edit subject. For a remote image, use `POST /images/uploads`. Returns the canonical image ID and whether an exact match already existed in the brand session.
- [Upload an image (signed)](https://docs.trybloom.ai/api-reference/images/upload-an-image-signed.md): Upload a local image as raw bytes (`multipart/form-data`) using a short-lived, single-use token from the `bloom_create_image_upload_url` MCP tool. The token in the path is the credential, so no `Authorization` header is expected. This endpoint uses the same exact-match reuse pipeline as `POST /image…
- [Semantic search](https://docs.trybloom.ai/api-reference/images/semantic-search.md): Search the brand session's library images by visual meaning, with the most similar results first. Library images have a `source` of `uploaded` (added by the user) or `scraped` (pulled in during onboarding); generated images are excluded. Images without a description or embedding are excluded from se…

## OpenAPI Specs

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