Skip to main content
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)."
}

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

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

​
Listing prompts

GET /{brand_id}/prompts returns active prompts by default. Pass the status query parameter to include archived prompts:
ValueReturns
active (default)Currently tracked prompts
archivedSoft-deleted prompts only
allBoth active and archived
# 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. 
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 →