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.

Brands belong to your company, not to a project. Every API key of your company, including a project key, can list, read, and refresh every brand, whichever project created it; the research run is charged to the project that started it. If you run a project per client and brand names are sensitive, don't give a client a project key of its own; see Projects.

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. is_default: true makes the brand your organization's default; your organization's first brand becomes its default either way. If you run a project per client, leave it false and set the brand as that client project's default_brand_profile_id instead; see Give each client its own brand. 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, internal service 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, plus brand_profile_id, revision, guideline_hash, generated_at, generation, and a deterministic markdown rendering. Evidence-bearing sections reference entries in research.sources and carry a confidence level. Unknown facts remain null or empty rather than being invented. Source URLs are served without utm_* tracking parameters, in research.sources and in markdown. generation.provider is pearl_engine for a researched guideline.

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, conflict (for example, your company already has the maximum number of active brands), not_ready, capability_disabled, insufficient_credits, quota_exceeded, budget_exceeded, and project_archived. Follow the error and retry guide; retry an ambiguous POST only with its original body and idempotency key.