Create once and retain both IDs
Submit brand source material toPOST /brand-skills. Bloom accepts the source,
starts processing asynchronously, and returns 202 Accepted with two IDs:
data.idis the Brand Skill ID, used as{id}in the Brand Skills API’s polling and deletion requests.data.brandIdis the ID of the created Brand.
data.id for the Brand Skill lifecycle.
We recommend sending a unique Idempotency-Key header for each Brand Skill you
intend to create. Requests without it are accepted, but retrying them may create
another Brand Skill. If a keyed request times out or returns a server error,
retry it with the same key and body. Bloom returns the original Brand Skill
instead of starting another job. Reusing a key with a different body returns
409 IDEMPOTENCY_CONFLICT.
instructions is part of that idempotent request body. Bloom removes
surrounding whitespace and treats a blank value as omitted. A retry with the
same normalized instructions replays the original Brand Skill; changing the
instructions while reusing the key returns 409 IDEMPOTENCY_CONFLICT.
The Brand Skills API accepts website and non-PDF file sources. A request
containing PDF bytes returns 400 INVALID_SOURCE before a Brand Skill is
queued, regardless of its URL or filename. Use a new request and key when any
source changes.
Persist both IDs before starting any later step. Include the Brand Skill ID when
contacting support about the build.
If creation returns 429 ACTIVE_JOB_LIMIT_REACHED, no Brand Skill was accepted
or queued. Wait for an active Brand Skill to finish, then retry the same body
and idempotency key if one was supplied. Bloom does not retry rejected creates
automatically.
Poll the same resource
CallGET /brand-skills/{id} until the status is completed or failed.
Wait 10 seconds before the first poll. After each non-terminal response, double
the interval to 20, 40, and then at most 60 seconds. Add a small random delay so
multiple jobs do not poll together. If polling returns 429 Too Many Requests,
wait for the number of seconds in the Retry-After response header before
resuming with the longer interval, or wait 60 seconds if the header is absent.
A failed resource includes a stable failure code and a retryable field. When
retryable is true, submit a new create request with a new idempotency key.
When it is false, keep the Brand Skill ID and contact Bloom.
The Get a Brand Skill reference
owns the exact lifecycle states and response fields.
Store the result before cleanup
A completed resource includes a temporary URL for its self-contained ZIP. Download it promptly and store or extract it in your own system. Successful bundle delivery starts Bloom’s automatic deletion clock. See Use the downloaded Skill for the folder contract. If the build fails, retain the Brand Skill ID and the returned failure details. Include the ID when contacting Bloom for a non-retryable failure. Do not share the source URL or API key.Optional immediate API removal
Bloom permanently removes the canonical Brand, Brand Skill, stored sources, generated ZIP, associated assets, and images generated under that Brand within 30 days of successful bundle delivery. Failed builds are also removed automatically. After your system has stored the completed Skill or recorded a failure, you may callDELETE /brand-skills/{id} to make it unavailable through the API
immediately and cancel active work when possible. This does not extend the
existing deletion schedule.
A ZIP URL is temporary and stops working when either its seven-day signature
expires or Bloom removes the underlying resource. The original idempotency key
is released when deletion is requested; reusing it starts a new create rather
than replaying the deleted ID.
The Delete a Brand Skill reference
contains the exact response and error definitions.