Request a brief

A brief gives your agent the brand context it needs for the task at hand.

Briefs are in private beta for selected accounts and are free during the beta. To request access, contact support@trybloom.ai.

What the brief contains

Bloom uses your brand to return Markdown guidance and selected assets: logos, images, fonts, and font renders. Each asset includes its kind, media type, and a stable Bloom URL. A font render shows the typeface; the font file lets your tool render text. The guidance can embed images and link to files using those same URLs. Keep the Bloom URLs: they redirect to fresh storage access with no scheduled expiry, while the brief, brand, saved Skill version, and asset remain available. Anyone with a link can open that asset without signing in. Bloom selects brand context without inventing unstated project details. For a general overview, read the Brand Skill.

Request and retrieve a brief

You’ll need a ready brand with an active Brand Skill. Describe your task in 1 to 4,000 characters, including any audience or constraints that matter.

With your API key, submit the brand and task:

curl -X POST https://www.trybloom.ai/api/v1/briefs \
  -H "x-api-key: $BLOOM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: q3-investor-deck-1" \
  -d '{
    "brandSessionId": "<brand_session_id>",
    "task": "An investor slide deck about our Q3 launch, covering the Pro line, EU expansion, and retention."
  }'

Replace the brand session ID. The 202 response contains data.id and data.status. Set BRIEF_ID to that ID:

curl "https://www.trybloom.ai/api/v1/briefs/$BRIEF_ID?wait=true&timeout=120" \
  -H "x-api-key: $BLOOM_API_KEY"

Repeat this read while pending or processing. Once completed, read data.guidance and data.assets. See Request a brief and Get a brief for the full contract.wait defaults to false. With waiting enabled, timeout defaults to 120 seconds and accepts integers from 1 to 295. A timeout leaves the brief running; fetch the same ID again.

Connect your agent, then ask:

Request a Bloom brief for our Q3 investor deck, covering the Pro line,
EU expansion, and retention. Use the Acme brand. Show me the guidance
and selected files before making the deck.

The agent calls create_brief, then get_brief with brief_id and wait: true, repeating reads while pending or processing. These tools appear only for beta accounts. Use the live tool schemas from tools/list; MCP fields differ from REST.Results include resource links and inline images when they fit within 7 MiB per image and 7 MiB per result. Download links remain available otherwise.

Only the creator can read a brief and must retain brand access. The returned skillId identifies the Skill version used and becomes null if that version is deleted.

Limits and recovery

An account can have 20 briefs pending or processing at once. At that limit, wait for one to finish. If the brand is not ready, wait for an active Skill.Retry a lost create response with the same input and Idempotency-Key in REST or idempotency_key in MCP. Use a new key for a new brief.Failed briefs return error.code, error.message, and error.retryable. When retryable, create a new brief with a new key. brief_not_applicable means brand context cannot help: it is not retryable. Read the agent’s message and revise the task. REST retrieval still returns HTTP 200; MCP returns structured data. Check status even when the read succeeds.

Add brief to an agent workflow

Give your original task, completed guidance, and selected files to the agent or application making the output. Your tools handle layout and production. Conflicting tasks can still receive a brief that identifies conflicts or unsupported assumptions and supplies relevant brand context. Try this with your MCP-connected agent:

Request a Bloom brief for an HTML slide deck about [Input your task here].
Then use the brief to create the deck.

Getting started

Guides

Use cases

MCP

Request a brief

What the brief contains

Request and retrieve a brief

Add brief to an agent workflow

​What the brief contains

​Request and retrieve a brief

​Add brief to an agent workflow

What the brief contains

Request and retrieve a brief

Add brief to an agent workflow