Retrieve and use a Brand Skill

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.

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.

Retrieve the active Skill

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

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:

{
  "data": {
    "schemaVersion": 3,
    "id": "f7e319aa-2a7f-4f2a-853a-eb5a5798659e",
    "skillId": "8a7a6a03-e399-4ae6-910b-1d50e936cc5c",
    "basedOnSkillId": null,
    "contentHash": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
    "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.

Cache by immutable identity

Use skillId as the canonical identity of the returned snapshot. If a later request returns the same skillId, it represents the same immutable Skill. contentHash is an opaque checksum of the stored artifact. It can be retained for comparison or integrity bookkeeping, but callers must not parse it or use it instead of skillId as the Skill identity. 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:

create a Brand from a website, guide, and brief;
wait until the Brand is ready;
retrieve its active Skill;
give the Skill to an agent that produces a deck or webpage; and
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.

Getting started

Guides

MCP

Retrieve and use a Brand Skill

Retrieve the active Skill

Cache by immutable identity

Refresh temporary font URLs

Use the Skill in another system

Handle unavailable Skills

​Retrieve the active Skill

​Cache by immutable identity

​Refresh temporary font URLs

​Use the Skill in another system

​Handle unavailable Skills

Retrieve the active Skill

Cache by immutable identity

Refresh temporary font URLs

Use the Skill in another system

Handle unavailable Skills