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

# Retrieve and use a Brand Skill

> Read one brand's complete active Skill from a server-side integration.

Bloom automatically uses a brand's active Skill when it generates images. A server-side integration that needs the complete brand context can retrieve the same Skill through the API and pass it to another system.

<Note>
  This guide documents the stable REST contract for retrieving an active Brand
  Skill. MCP clients can inspect brand context through the capabilities in their
  live `tools/list` response; dynamically discovered MCP schemas are not
  duplicated here as a public contract.
</Note>

## Retrieve the active Skill

Call `GET /brands/{id}/skill` with the stable Brand ID:

```bash theme={null}
curl "https://www.trybloom.ai/api/v1/brands/$BRAND_ID/skill" \
  -H "x-api-key: $BLOOM_API_KEY"
```

No model runs during this request. Bloom returns one immutable snapshot containing:

* the exact Skill identity and creation time;
* the safe structured brand profile;
* every Markdown file in the active Skill; and
* the Brand Library asset IDs referenced by each file.

The response follows this shape:

```json theme={null}
{
  "data": {
    "schemaVersion": 4,
    "id": "f7e319aa-2a7f-4f2a-853a-eb5a5798659e",
    "skillId": "8a7a6a03-e399-4ae6-910b-1d50e936cc5c",
    "basedOnSkillId": null,
    "createdAt": "2026-09-14T12:00:00.000Z",
    "profile": {
      "name": "Acme",
      "primaryLogo": {
        "assetId": "2c452e3f-b884-4684-b80f-523814d27899"
      },
      "colors": [{ "hex": "#112233" }],
      "typography": {
        "heading": { "source": "google", "family": "Instrument Serif" },
        "body": { "source": "google", "family": "Inter" }
      }
    },
    "files": [
      {
        "path": "SKILL.md",
        "content": "---\nname: acme\n---\n...",
        "libraryAssetIds": []
      }
    ]
  }
}
```

The exact profile union, font metadata, and error schemas live in the [`GET /brands/{id}/skill` reference](/api-reference/brands/inspect-a-brands-active-skill).

## Cache by immutable identity

Use `skillId` as the canonical identity and cache key for the complete returned snapshot. If two responses have the same `skillId`, they represent the same immutable brand revision. If their `skillId` values differ, reload the revision even when some fields happen to be unchanged.

`basedOnSkillId` identifies the base Skill when the current Skill was derived from an earlier version. It is `null` when that relationship is unavailable.

## Refresh temporary font URLs

Custom typography can include temporary signed font URLs inside `profile`. Cache the Skill's durable fields by `skillId`, but retrieve the active Skill again when a font URL expires. A refreshed URL does not change the Skill's identity.

## Use the Skill in another system

Pass the structured profile and Markdown files to the system doing the work, and retain `skillId` with the resulting artifact or job record. That preserves which brand context informed the result.

For example, an application can:

1. create a brand from a website, guide, and brief;
2. wait until the brand is ready;
3. retrieve its active Skill;
4. give the Skill to an agent that produces a deck or webpage; and
5. record `skillId` beside the finished output.

Bloom supplies the brand context. The calling application owns the external workflow, renderer, and output.

## Handle unavailable Skills

* `404 BRAND_NOT_FOUND` means the brand does not exist or is not accessible to the caller.
* `409 BRAND_SKILL_UNAVAILABLE` means the brand does not have an active inspectable Skill, including while a new brand is still processing.
* `500 INTERNAL_ERROR` means Bloom could not inspect the Skill; retry according to the application's normal transient-error policy.

Do not retry `404` without changing the Brand ID or caller. For `409`, check `GET /brands/{id}` and wait for `status: "ready"` before trying again.