# Brands

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

Canonical guide: <https://api.blackpearl.com/docs/brands>

Raw Markdown: <https://api.blackpearl.com/docs/raw/brands.md>

OpenAPI: <https://api.blackpearl.com/v1/openapi.json>

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.

```bash
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`:

```bash
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](https://api.blackpearl.com/docs/errors); 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.