# Brands

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

Canonical guide: <https://engine.neraperla.com/docs/brands>

Raw Markdown: <https://engine.neraperla.com/docs/raw/brands.md>

OpenAPI: <https://engine.neraperla.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.

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](https://engine.neraperla.com/docs/projects#give-each-client-its-own-brand).

## 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. `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](https://engine.neraperla.com/docs/projects#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`:

```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`, 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](https://engine.neraperla.com/docs/errors); retry an ambiguous POST only with its original body and idempotency key.
