> ## 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.

# Request a brief

> Get the brand guidance and files that apply to what you are about to make.

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

<Note>
  Briefs are in private beta for selected accounts and are free during the beta.
  To request access, contact [support@trybloom.ai](mailto:support@trybloom.ai).
</Note>

## 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](/guides/use-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.

<Tabs>
  <Tab title="API">
    With your [API key](/api/authentication), submit the brand and task:

    ```bash theme={null}
    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:

    ```bash theme={null}
    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](/api-reference/briefs/request-a-brief) and [Get a brief](/api-reference/briefs/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.
  </Tab>

  <Tab title="MCP">
    [Connect your agent](/mcp/connect), then ask:

    ```text theme={null}
    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](/mcp/tools#briefs) 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.
  </Tab>
</Tabs>

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.

<Accordion title="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.
</Accordion>

## 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:

```text theme={null}
Request a Bloom brief for an HTML slide deck about [Input your task here].
Then use the brief to create the deck.
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.