Brands

Turn a company name or website into a versioned, evidence-backed brand guideline.

Brands creates a reusable identity and messaging foundation for downstream documents, presentations, Playbooks, campaigns, and templates. Supply a company name, an official website, or both. The platform enqueues web research and stores the completed result as a strict, versioned guideline rather than an unstructured report.

Create and poll a brand#

Operation create_brand_v1_brands_post creates a Brand and starts its first research Job.

Send an Idempotency-Key with the first request and retain it until the returned job ID is stored. Matching retries within 24 hours replay the original response and do not create a duplicate profile.

curl --fail-with-body --silent --show-error \
  --request POST "$BLACKPEARL_API_BASE_URL/v1/brands" \
  --header "Authorization: Bearer $BLACKPEARL_API_KEY" \
  --header "Idempotency-Key: brand-20260716-acme" \
  --header "Content-Type: application/json" \
  --data '{
    "company_name": "Acme Corporation",
    "website_url": "https://acme.example",
    "is_default": false
  }'

At least one of company_name and website_url is required. The response is a typed asynchronous job with type: "brands". Poll GET /v1/jobs/{job_id} until status is succeeded, failed, or canceled. A successful result contains brand_profile_id, schema_version, revision, guideline_hash, source_count, and guideline_path.

Read brand state#

Operation list_brands_v1_brands_get uses GET /v1/brands to list active brands. Operation get_brand_v1_brands__brand_id__get uses GET /v1/brands/{brand_id} to inspect one. Both expose safe state metadata such as research_status, research_job_id, guideline_available, guideline_revision, and source_count. They do not expose raw provider responses, traces, credentials, Server.Bebop identifiers, or the internal branding snapshot.

research_status is one of not_started, queued, researching, ready, failed, or canceled. If a refresh fails, the previous successful guideline remains stored and readable.

Consume the guideline#

After the job succeeds, use operation get_brand_guideline_v1_brands__brand_id__guideline_get at the path returned in result.guideline_path:

curl --fail-with-body --silent --show-error \
  "$BLACKPEARL_API_BASE_URL/v1/brands/$BRAND_ID/guideline" \
  --header "Authorization: Bearer $BLACKPEARL_API_KEY"

The response has stable sections for identity, foundations, audience, positioning, voice, messaging, visual, applications, governance, and research. Evidence-bearing sections reference entries in research.sources and carry a confidence level. Unknown facts remain null or empty rather than being invented.

Bind brand_profile_id, revision, and guideline_hash to each downstream artifact. Do not silently change guideline revisions in the middle of a generation job. Treat generated claims and external material as reviewable context: a guideline does not authorize publishing, outreach, or writes to another system.

Refresh and errors#

Operation research_brand_v1_brands__brand_id__research_post starts a new revision with POST /v1/brands/{brand_id}/research. When a run is already active, the endpoint returns that job instead of enqueuing another.

Common failures include invalid_request, brand_profile_not_found, brand_profile_archived, not_ready, capability_disabled, insufficient_credits, quota_exceeded, and budget_exceeded. Follow the error and retry guide; retry an ambiguous POST only with its original body and idempotency key.

The complete runtime configuration, schema inventory, research safeguards, and downstream invariants are documented in the repository's docs/brands-api.md operator reference.