Skip to main content
This walkthrough creates one Brand Skill from a website, then downloads the completed folder. Bloom schedules its retained copy for deletion automatically.

​
Before you start

You need:
  • a dedicated Bloom API key created from the approved account that will own the integration (create one in Account);
  • one or more public website or non-PDF file sources; and
  • a server-side environment where the API key remains secret, with curl and jq installed.
The idempotency key is optional but recommended. Use a new value for each Brand Skill you intend to create, and reuse it only when retrying the same request body.

​
1. Create the Brand Skill

This example creates a Brand Skill from a website:
Bloom validates the website, queues the build, and returns 202 Accepted:
The response contains two IDs:
  • data.id is the Brand Skill ID. The command saves it as BRAND_SKILL_ID; use it to check the build and delete the Brand Skill.
  • data.brandId is the ID of the created Brand.
Save both values in your job record. The polling response also includes both IDs. The create reference owns the exact source schemas and limits.
The Brand Skills API does not accept PDFs. They are rejected from their verified contents, even when the URL or filename uses another extension. Bloom deletes the staged copy before returning 400 INVALID_SOURCE and does not queue a Brand Skill. If cleanup fails after retries, the request returns an internal error instead. Other file types remain supported.
instructions is optional, applies only to this Brand Skill run, and may contain up to 4,000 characters after surrounding whitespace is removed. Bloom passes it to the Brand Agent as customer guidance for authoring the Skill. The Agent decides how to apply it under its existing instructions, so do not treat it as a strict output guarantee.

​
2. Check the build

Repeat this request until data.status is completed or failed. Wait 10 seconds before the first check, then double the interval after each non-terminal response up to 60 seconds. Add a small random delay when polling several Brand Skills so their requests do not arrive together. If a check returns 429 Too Many Requests, wait for the number of seconds in the Retry-After response header before checking again, or wait 60 seconds if the header is absent. When the build completes, data.download contains the temporary ZIP URL, filename, and byte length. The get reference contains the complete response schema.

​
3. Download and extract the Skill

Copy data.download.url from the completed response:
Store the whole extracted folder and preserve its relative paths. Continue to Use the downloaded Skill before wiring it into an agent.

​
4. Optional: remove API access immediately

Bloom removes the Brand Skill and its inputs and derived outputs within 30 days of successful bundle delivery. You do not need to call DELETE to start this clock. After your system has stored the Skill, you may hide it from the API immediately:
Deletion makes the resource unavailable immediately without extending its existing purge schedule. The create request’s idempotency key becomes available for a new Brand Skill as soon as deletion is requested.

Build the production lifecycle

Add safe polling, failure handling, storage, and cleanup to your backend.