Quickstart - Bloom Brand Skills API

This walkthrough creates one Brand Skill from a website and PDF, downloads the completed folder, and removes Bloom’s retained copy.

Before you start

You need:

the dedicated Bloom API key issued for your integration;
a public website URL, a temporary public PDF URL, or both; and
a server-side environment where the API key remains secret.

export BLOOM_API_KEY=bloom_sk_...

1. Create the Brand Skill

This example combines a website and PDF in one Brand Skill:

curl --request POST "https://www.trybloom.ai/api/v1/brand-skills" \
  --header "x-api-key: $BLOOM_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "brandName": "Acme",
    "sources": [
      {
        "kind": "website",
        "url": "https://acme.com"
      },
      {
        "kind": "pdf",
        "url": "https://uploads.example.com/acme-brand-guide.pdf",
        "filename": "acme-brand-guide.pdf"
      }
    ]
  }'

Bloom downloads the PDF during this request, queues the build, and returns 202 Accepted:

{
  "data": {
    "id": "00000000-0000-4000-8000-000000000000",
    "status": "pending"
  }
}

Save data.id in your job record:

export BRAND_SKILL_ID=00000000-0000-4000-8000-000000000000

The create reference owns the exact source schemas and limits.

2. Check the build

curl "https://www.trybloom.ai/api/v1/brand-skills/$BRAND_SKILL_ID" \
  --header "x-api-key: $BLOOM_API_KEY"

Repeat this request until data.status is completed or failed. Start with a five-second interval and back off between later requests. 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:

export BRAND_SKILL_DOWNLOAD_URL="https://..."

curl --location "$BRAND_SKILL_DOWNLOAD_URL" --output brand-skill.zip
unzip brand-skill.zip -d brand-skill

Store the whole extracted folder and preserve its relative paths. Continue to Use the downloaded Skill before wiring it into an agent.

4. Delete Bloom’s copy

After your system has stored the Skill:

curl --request DELETE \
  "https://www.trybloom.ai/api/v1/brand-skills/$BRAND_SKILL_ID" \
  --header "x-api-key: $BLOOM_API_KEY"

Deletion removes the source files, generated ZIP, and Brand Skill resource held by Bloom.

Build the production lifecycle

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

​Before you start

​1. Create the Brand Skill

​2. Check the build

​3. Download and extract the Skill

​4. Delete Bloom’s copy