> ## 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.
# Create a brand
> Turn websites, Instagram accounts, files, and instructions into a ready brand.
Create a brand once, wait for its source evidence to become an active Brand Skill, then use the stable Brand ID for later work.
```mermaid theme={null}
flowchart LR
A["Submit sources"] --> B["Brand Agent"] --> C["Ready brand + active Skill"]
```
Use the API for application or server code. Use MCP when an interactive agent is operating Bloom.
## Choose the source evidence
A source-based request accepts up to 30 entries, with at most one website and one Instagram account. Files can supply brand guides, briefs, logos, covers, and other useful evidence.
* Website sources use `{ "kind": "website", "url": "https://..." }`.
* Instagram sources use `{ "kind": "instagram", "username": "acme" }`.
* File sources use `{ "kind": "file", "url": "https://...", "filename": "..." }`.
File URLs must use HTTPS and remain publicly reachable while the request runs. Bloom copies the bytes into private storage before the Brand Agent begins. `filename` labels a source; it does not tell Bloom what role the file should play.
Bloom determines the brand name from the evidence. Pass `workspaceId` in the API or `workspace_id` in MCP when the brand should belong to a team workspace; otherwise creation defaults to the caller's personal workspace.
## Tell the Brand Agent what matters
`instructions` is optional, accepts up to 4,000 characters, and applies only to this Brand Agent run. Use it to:
* identify the role or authority of a supplied file;
* emphasize evidence important to the application; or
* request additional guidance that the resulting Brand Skill should cover.
The Brand Agent applies the request using its existing judgment. `instructions` is not a strict output guarantee.
## Start creation
Send the ordered source set to `POST /brands`:
```bash theme={null}
curl -X POST https://www.trybloom.ai/api/v1/brands \
-H "x-api-key: $BLOOM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"sources": [
{ "kind": "website", "url": "https://acme.com" },
{
"kind": "file",
"url": "https://uploads.acme.com/temporary-brand-guide.pdf",
"filename": "brand-guide.pdf"
}
],
"instructions": "Create an imagery.md file that explains how image-heavy this brand is and what imagery it uses."
}'
```
Bloom returns `202 Accepted` after the work is queued:
```json theme={null}
{
"data": {
"id": "f7e319aa-2a7f-4f2a-853a-eb5a5798659e",
"status": "analyzing"
}
}
```
Once [Bloom MCP is connected](/mcp/connect), ask the agent to create the brand from the same evidence:
```text theme={null}
Create a brand in Bloom from acme.com and the brand guide at
https://uploads.acme.com/temporary-brand-guide.pdf. Ask the Brand Agent to
create an imagery.md file explaining how image-heavy the brand is and what
imagery it uses.
```
An integration calling `bloom_onboard_brand` directly can pass:
```json theme={null}
{
"sources": [
{ "kind": "website", "url": "https://acme.com" },
{
"kind": "file",
"url": "https://uploads.acme.com/temporary-brand-guide.pdf",
"filename": "brand-guide.pdf"
}
],
"instructions": "Create an imagery.md file that explains how image-heavy this brand is and what imagery it uses."
}
```
Both interfaces return the stable Brand ID while processing continues. Keep that ID for status checks, Brand Skill retrieval, and image operations.
## Wait until the brand is ready
Retrieve the brand with `wait=true`:
```bash theme={null}
curl "https://www.trybloom.ai/api/v1/brands/$BRAND_ID?wait=true" \
-H "x-api-key: $BLOOM_API_KEY"
```
Call `bloom_get_brand` with the returned ID and `wait: true`.
Each call waits for a bounded period. If either interface returns `status: "analyzing"`, repeat the same request with the same Brand ID. Generate only after the brand becomes `ready`.
## Supply a specific logo
Include the approved logo as a file source and name its role explicitly:
```json theme={null}
{
"sources": [
{ "kind": "website", "url": "https://acme.com" },
{
"kind": "file",
"url": "https://uploads.acme.com/brand-logo.png",
"filename": "brand-logo.png"
}
],
"instructions": "The attached image is the approved primary logo."
}
```
When several logos are supplied, identify each one as primary, alternate, deprecated, tentative, or reference-only. Prefer PNG or WebP when a supplied file should become the profile's primary logo.
After the brand is ready, `GET /brands/{id}` returns the selected logo in `profile.primaryLogo`. The complete active Skill provides its exact asset identity.
## Handle failures
If Bloom rejects the creation request, correct the source or instructions before retrying. Common API validation codes include `INVALID_URL`, `UNSUPPORTED_SOURCE`, and `INVALID_SOURCE`; MCP returns the corresponding validation failure through the tool result.
After creation is queued, a failed brand includes a stable failure code and a human-readable message. Show the message, correct the input, and submit a new creation request.
## Compatibility inputs
The API and MCP retain a single website or Instagram `url` input for existing integrations. A plain `url` creates a Brand Skill through the same source-first pipeline. New integrations should use `sources` so they can combine evidence and provide `instructions`.
Adding `logoUrl` to an API request, or `logo_url` to an MCP request, switches the request to the older explicit-logo onboarding workflow. That compatibility path can return `logo_required`; supply a replacement logo and wait for the brand again before generating.
## Next steps
* [Retrieve and use the active Brand Skill](/guides/use-brand-skill)
* [Generate images with the brand](/guides/generate-images)
* Inspect the exact [`POST /brands`](/api-reference/brands/create-a-brand) contract