Configuration API: Manage Brands and Prompts

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

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

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
      }
    ]
  }'

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

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.

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

Asynchronous website validation

After a write commits, Scrunch checks each new or changed website URL in the background. The checks confirm that the hostname resolves to a public address and that the page responds over HTTP. These checks are advisory. They never delay, reject, or roll back a structurally valid save, so your API response is unaffected. Background checks run for URLs submitted through:

POST /brands and PATCH /brands/{brand_id} (brand website, alternative_websites, and competitor websites in the replacement list)
POST /brands/{brand_id}/competitors and PUT /brands/{brand_id}/competitors/{competitor_id} (websites)

Only new or changed URLs are checked. Malformed URLs are still rejected synchronously at write time, before the background checks run. If any check fails, Scrunch creates one aggregated notification in the dashboard notification bell for the user who owns the API key. Other users of the brand are not notified. Clicking the notification opens Configure → Brand Entities with a banner listing each affected URL and its result, such as page not found or host did not resolve. If a check could not be completed, the notification says so explicitly. An incomplete check does not mean the URL is invalid. Successful checks are silent. To clear a warning, correct the URL with another write; the updated URL is checked again. Responses that only block automated access (401, 403, or 429) do not create a warning. Sites often return these codes to automated clients while remaining reachable in a browser, so they do not indicate that the URL is invalid. If a run contains both blocked-access results and other failures, the notification reports only the other failures.

# The save succeeds immediately even if the website is unreachable.
# A warning notification appears in the dashboard afterward.
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://spiritt-typo.com"
  }'

URL-validation warnings are independent of brand-performance notification preferences and cannot be disabled by those settings.

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.

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"]
  }'

Excluded names

Use excluded_names to list phrases that should never count as a mention of a brand or competitor, even when the phrase contains a configured name as a word. This lets a brand named Caliber match Caliber Collision while ignoring unrelated entities like Caliber Car Wash or Caliber Fitness. Scrunch blanks every word-boundary occurrence of each excluded phrase before searching the response for this entity’s names. Position and other span-based metrics are unaffected because masked spans are replaced with equal-length whitespace. Historical responses are re-evaluated when excluded_names changes, so metrics update without a manual backfill. excluded_names is a list of strings and is available on:

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

curl -X POST "https://api.scrunchai.com/v1/brands" \
  -H "Authorization: Bearer $SCRUNCH_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Caliber",
    "website": "https://caliber.com",
    "excluded_names": ["Caliber Car Wash", "Caliber Fitness", "Caliber Armor"]
  }'

Each brand and competitor accepts up to 100 entries in excluded_names. Submitting more returns a 422 Unprocessable Entity with:

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

Scrunch rejects an exclusion that equals the entity’s own name or any of its alternative_names, since either would remove every mention of the entity. Remove the alternative name instead of excluding it. The check runs after Scrunch normalizes punctuation, so Caliber. and Caliber are treated as the same phrase.

Example: Add a prompt

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"]
  }'

Tag name limit

Each entry in a prompt’s tags array is limited to 64 characters. Submitting a longer tag name to POST /{brand_id}/prompts returns a 400 Bad Request with a structured detail object:

{
  "detail": {
    "code": "tag_name_too_long",
    "tag": "budget airlines, low cost carriers, cheap flights, best value airlines",
    "max_length": 64,
    "message": "Tag 'budget airlines, low cost carriers, cheap flights, best value …' is longer than 64 characters. Separate multiple tags with commas."
  }
}

The check runs before any tag is created, so a request with one over-long name creates no tags at all. Over-long names usually come from joining several tags into a single string. Send each tag as its own array entry instead:

{ "tags": ["budget", "low cost", "best value"] }

Tag names at exactly 64 characters are accepted. The limit applies only when creating tags; referencing existing tags is unaffected.

Duplicate prompt text

POST /{brand_id}/prompts checks the new text against the brand’s existing prompts. The outcome depends on the existing prompt’s status:

Active duplicate — returns 400 Bad Request with the message Prompt already exists.

Paused duplicate — returns 400 Bad Request with a structured detail object identifying the paused prompt, so you can resume it instead of creating a copy:

{
  "detail": {
    "type": "paused_duplicate",
    "message": "A paused prompt with this text already exists",
    "prompt_id": 5678
  }
}

Archived duplicate — reactivates the archived prompt instead of returning an error.

Listing prompts

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

Value	Returns
`active` (default)	Currently tracked prompts
`paused`	Prompts whose collection is paused; their history stays visible
`archived`	Soft-deleted prompts only
`all`	Active, paused, and archived prompts

Any other value returns a 422 Unprocessable Entity rather than an empty list.

# Only paused prompts
curl "https://api.scrunchai.com/v1/$BRAND_ID/prompts?status=paused" \
  -H "Authorization: Bearer $SCRUNCH_API_KEY"

# All prompts including paused and 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, paused, or archived

For paused prompts, platforms and variants reflect the prompt’s active variants. Pausing never changes them, so they show what a resume would collect again. GET /{brand_id}/prompts/{prompt_id} returns archived prompts as well, so check the status field if you only want active ones.

Pausing and resuming prompts

PATCH /{brand_id}/prompts/{prompt_id} moves a prompt between active and paused. It requires the configure scope, and status is the only field the body accepts.

# Pause a prompt
curl -X PATCH "https://api.scrunchai.com/v1/$BRAND_ID/prompts/$PROMPT_ID" \
  -H "Authorization: Bearer $SCRUNCH_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "status": "paused" }'

# Resume it
curl -X PATCH "https://api.scrunchai.com/v1/$BRAND_ID/prompts/$PROMPT_ID" \
  -H "Authorization: Bearer $SCRUNCH_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "status": "active" }'

Pausing stops collection and releases the prompt’s variants from the organization’s prompt pool. The prompt keeps its configuration and all of its collected history, and stays readable through GET /{brand_id}/prompts?status=paused. Resuming restores the exact deployment the prompt had when it was paused. Scrunch re-checks the prompt pool first, so a resume can return 429 with a quota_exceeded error when the organization no longer has room for the prompt’s variants. Both transitions are idempotent: a prompt already in the requested status returns 200 with the prompt, unchanged. archived is not accepted as a target status; archive a prompt with DELETE /{brand_id}/prompts/{prompt_id} instead. A transition the prompt’s current state does not allow returns 409 with a detail.type naming the reason:

`detail.type`	Meaning
`is_archived`	Archived prompts cannot be paused or resumed
`persona_archived`	The prompt’s persona is archived; `detail.blocking_persona_ids` lists the personas to restore or reassign before resuming
`active_duplicate`	An active prompt with the same text, persona, and country already exists
`no_active_variants`	The prompt has no active variants, so resuming it would collect nothing

A 503 with detail.type of pause_failed or resume_failed means the transition did not complete. Retry the request.

Archiving a persona pauses its prompts

Archiving a persona pauses its active custom prompts instead of archiving them. Collection and billing stop, but the prompts’ collected history stays visible on the Responses and Query APIs. The paused prompts appear under status=paused in the prompt listing. This applies to every path that archives a persona:

DELETE /brands/{brand_id}/personas/{persona_id}
PATCH /brands/{brand_id} when the personas replace-list omits an existing persona

Prompts that reference the persona only through variants keep collecting on their remaining active variants; a prompt left with no active variant is paused. Already paused, archived, and industry prompts are not affected. To resume the paused prompts, restore the persona or reassign the prompts to another persona, then resume them.

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.

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:

{
  "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.

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.

Notes

To update prompt text, delete the old prompt and create a new one. Only tags and platforms can be updated in-place.

See all configuration endpoints

Explore the API reference →

Query API

Responses API

Agent Traffic API

AI Referrals API

Site Audit API

Crawl Readiness API

Signals API

Site Optimization API

Audit Scores API

Sitemap API

Collection API

AXP Render API

Optimize & Deploy API

Webhooks