> ## Documentation Index
> Fetch the complete documentation index at: https://developers.scrunch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration API: Manage Brands and Prompts

> Create brands, manage competitors and personas, and configure tracking prompts via the Scrunch Configuration API to automate client onboarding.

The Configuration API lets you manage Scrunch brands at scale.\
It is most commonly used by:

* Agencies onboarding dozens or hundreds of clients
* Enterprise teams automating persona and keyword setup
* Internal tools (brand creation, batch updates, auditing)

***

## What you can configure

### Brands

* Name, alternative names
* Website + alternative websites
* Competitors
* Personas
* Key topics

### Prompts

* Text
* Stage
* Tags
* Personas
* Platforms

***

## Example: Create a brand

```bash theme={null}
curl -X POST "https://api.scrunchai.com/v1/brands" \
  -H "Authorization: Bearer $SCRUNCH_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Spirit Airlines",
    "website": "https://spirit.com",
    "description": "Low cost air carrier."
  }'
```

***

## Case-sensitive name matching

By default, Scrunch matches brand and competitor names against AI responses case-insensitively, so `"spirit airlines"`, `"Spirit Airlines"`, and `"SPIRIT AIRLINES"` all count as mentions. For names that are common words, acronyms, or stylized in a specific case (for example, `NeXT`, or `LUSH`), enable case-sensitive matching to avoid false positives.

Set `case_sensitive: true` on a brand or competitor to require exact-case matches for `name` and `alternative_names`. The flag defaults to `false` and is available on:

* `POST /brands` — on the brand body and on each entry in `competitors[]`
* `PATCH /brands/{brand_id}` — on the brand and on each competitor in the replacement list
* `POST /brands/{brand_id}/competitors` and `PUT /brands/{brand_id}/competitors/{competitor_id}`
* `GET` responses for brands and competitors return the current value

```bash theme={null}
curl -X POST "https://api.scrunchai.com/v1/brands" \
  -H "Authorization: Bearer $SCRUNCH_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "LUSH",
    "website": "https://lush.com",
    "case_sensitive": true,
    "competitors": [
      {
        "name": "The Body Shop",
        "case_sensitive": false
      }
    ]
  }'
```

<Note>Changing `case_sensitive` on an existing brand triggers a re-evaluation of historical responses against the new matching rule.</Note>

## Domain uniqueness across brand and competitors

Each domain can only be classified one way within a brand — either as the brand's own or as one specific competitor's. This keeps citation owner classification (`brand` / `competitor` / `other`) deterministic.

Scrunch normalizes every configured URL by stripping the scheme, `www.`, query, fragment, and trailing slash, and lowercasing it. The brand's primary `website` is compared by domain only, while `alternative_websites` and competitor `websites` keep their path — so `example.com/a` and `example.com/b` on two different owners do not conflict. If a write would assign the same normalized domain to two different owners (for example, the brand's `website` and a competitor's `websites`, or two competitors), the request is rejected with HTTP `409` and a `detail` describing where the domain is already used. The check applies to:

* `POST /brands` and `PATCH /brands/{brand_id}` (brand `website`, `alternative_websites`, and the replacement `competitors[]`)
* `POST /brands/{brand_id}/competitors` and `PUT /brands/{brand_id}/competitors/{competitor_id}`

Only newly introduced conflicts are blocked, so unrelated edits to a brand that already contains a legacy collision still save. To move a domain between owners, remove it from the current owner in the same request that adds it to the new one.

```json theme={null}
{
  "detail": "example.com is already configured as the competitor 'Acme' for this brand. A domain can only be classified one way (brand vs. competitor)."
}
```

## Alternative names limit

Each brand and competitor accepts up to **100 entries** in `alternative_names`. Submitting more returns a `422 Unprocessable Entity` with the message:

```
alternative_names cannot exceed 100 entries (got N); remove some before saving
```

The cap is enforced on every write endpoint that accepts `alternative_names`, including:

* `POST /v1/brands` and `PATCH /v1/brands/{brand_id}` (brand body and each competitor)
* `POST /v1/brands/{brand_id}/competitors` and `PUT /v1/brands/{brand_id}/competitors/{competitor_id}`

If you previously sent more than 100 aliases, the collection layer silently kept only the 100 shortest. Trim your list before retrying so you control which aliases are retained.

```bash theme={null}
curl -X POST "https://api.scrunchai.com/v1/brands" \
  -H "Authorization: Bearer $SCRUNCH_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Spirit Airlines",
    "website": "https://spirit.com",
    "description": "Low cost air carrier.",
    "alternative_names": ["Spirit", "Spirit Air", "NK"]
  }'
```

## Example: Add a prompt

```bash theme={null}
curl -X POST "https://api.scrunchai.com/v1/1234/prompts" \
  -H "Authorization: Bearer $SCRUNCH_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "What are the best budget airlines?",
    "tags": ["budget"],
    "platforms": ["chatgpt", "perplexity"]
  }'
```

## Listing prompts

`GET /{brand_id}/prompts` returns active prompts by default. Pass the `status` query parameter to include archived prompts:

| Value              | Returns                   |
| ------------------ | ------------------------- |
| `active` (default) | Currently tracked prompts |
| `archived`         | Soft-deleted prompts only |
| `all`              | Both active and archived  |

```bash theme={null}
# All prompts including archived ones
curl "https://api.scrunchai.com/v1/$BRAND_ID/prompts?status=all" \
  -H "Authorization: Bearer $SCRUNCH_API_KEY"
```

Each prompt in the response includes:

* `branded` — `true` if the prompt mentions the brand
* `favorite` — `true` if marked as a favorite in the dashboard
* `status` — `active` or `archived`

`GET /{brand_id}/prompts/{prompt_id}` returns archived prompts as well, so check the `status` field if you only want active ones.

***

## Reusing an archived persona name

When you `PATCH /brands/{brand_id}` with personas, the list represents the full desired state: existing personas not included are archived.

If you later submit a persona without an `id` and the `name` matches a previously archived persona on the same brand, Scrunch reactivates the archived record instead of failing on the unique-name constraint. Its `status` returns to `active` and the `description` is replaced with the value you provide.

```bash theme={null}
curl -X PATCH "https://api.scrunchai.com/v1/brands/$BRAND_ID" \
  -H "Authorization: Bearer $SCRUNCH_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "personas": [
      { "name": "Budget Traveler", "description": "Price-sensitive consumer" }
    ]
  }'
```

If `Budget Traveler` was previously archived on this brand, the call reactivates that persona and updates its description. To update an existing active persona instead, include its `id`.

***

## Persona limits when creating a brand

`POST /brands` accepts an optional `personas` array. Each plan caps how many personas you can attach to a single brand. If the array is longer than your plan allows, the request is rejected before the brand is created — no partial brand is saved.

When the limit is exceeded, the API returns `429 Too Many Requests` with a `quota_exceeded` error:

```json theme={null}
{
  "detail": {
    "error": "quota_exceeded",
    "feature_key": "brand.personas.count",
    "limit": 3,
    "used": 5,
    "message": "This plan allows up to 3 personas per brand; received 5."
  }
}
```

To recover, trim the `personas` array to `limit` entries or fewer and retry the request. To find your plan's limit, inspect the `limit` field in the error response or contact your account team.

<Tip>
  Personas can also be added or replaced after a brand is created via `POST /brands/{brand_id}/personas` and `PATCH /brands/{brand_id}`. The cap is currently enforced only at brand creation.
</Tip>

***

### Notes

<Note> To update prompt text, delete the old prompt and create a new one. Only tags and platforms can be updated in-place. </Note>
<Card title="See all configuration endpoints" icon="gears" href="/api-reference"> Explore the API reference → </Card>