Sites

Site/brand management and Brand DNA

List all sites/brands

get

Returns a list of all sites (brands) for your team. Use site IDs when creating content to enable Brand DNA features.

Authorizations

ApiKeyAuth

X-API-KEYstringRequired

Query parameters

pageintegerOptional

Page number for pagination

Responses

200

A list of sites

application/json

idstring · uuidOptional

domainstringOptional

The domain/URL of the site

icon_urlstring · nullableOptional

URL to the site favicon or icon

statusstring · enumOptionalPossible values:

created_atstring · date-timeOptional

updated_atstring · date-time · nullableOptional

get

/v1/sites

HTTPcURLJavaScriptPython

GET /v1/sites HTTP/1.1
Host: api.cuppa.ai
X-API-KEY: YOUR_API_KEY
Accept: */*

200

A list of sites

[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "text",
    "icon_url": "text",
    "status": "active",
    "created_at": "2026-03-22T03:46:23.666Z",
    "updated_at": "2026-03-22T03:46:23.666Z"
  }
]

Create a new site/brand

post

Create a new site/brand with full Brand DNA onboarding. The brand analysis (company info, competitors, voice, visual style) is automatically queued and completes in 1-2 minutes.

Authorizations

ApiKeyAuth

X-API-KEYstringRequired

Body

application/json

domainstringRequired

The domain of the site (e.g., "example.com")

namestringOptional

Optional display name for the brand

Responses

201

Site created and Brand DNA queued

application/json

409

Site already exists

application/json

post

/v1/sites

HTTPcURLJavaScriptPython

POST /v1/sites HTTP/1.1
Host: api.cuppa.ai
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 31

{
  "domain": "text",
  "name": "text"
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "domain": "text",
  "status": "queued",
  "message": "text"
}

Get a site by ID

get

Authorizations

ApiKeyAuth

X-API-KEYstringRequired

Path parameters

idstring · uuidRequired

The site ID

Responses

200

The site object

application/json

idstring · uuidOptional

domainstringOptional

The domain/URL of the site

icon_urlstring · nullableOptional

URL to the site favicon or icon

statusstring · enumOptionalPossible values:

created_atstring · date-timeOptional

updated_atstring · date-time · nullableOptional

get

/v1/sites/{id}

HTTPcURLJavaScriptPython

GET /v1/sites/{id} HTTP/1.1
Host: api.cuppa.ai
X-API-KEY: YOUR_API_KEY
Accept: */*

200

The site object

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "domain": "text",
  "icon_url": "text",
  "status": "active",
  "created_at": "2026-03-22T03:46:23.666Z",
  "updated_at": "2026-03-22T03:46:23.666Z"
}

Get all brand information for a site

get

Returns brand context, voices, and visual style in a single request.

Authorizations

ApiKeyAuth

X-API-KEYstringRequired

Path parameters

idstring · uuidRequired

The site ID

Responses

200

Brand information

application/json

get

/v1/sites/{id}/brand

HTTPcURLJavaScriptPython

GET /v1/sites/{id}/brand HTTP/1.1
Host: api.cuppa.ai
X-API-KEY: YOUR_API_KEY
Accept: */*

200

Brand information

{
  "context": {
    "company_name": "text",
    "description": "text",
    "industry": "text",
    "target_audience": "text",
    "value_proposition": "text",
    "competitors": {},
    "ranking_keywords": {},
    "pain_points": {},
    "faq_questions": {}
  },
  "voices": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "description": "text",
      "is_active": true,
      "values": {}
    }
  ],
  "visual_style": {
    "logo_url": "text",
    "primary_color": "text",
    "secondary_color": "text",
    "accent_color": "text",
    "primary_font": "text",
    "visual_mood": "text"
  }
}

Get GSC search queries for a site

get

Returns Google Search Console query data including clicks, impressions, position, and opportunity scores. Requires Power plan or higher and GSC to be connected.

Authorizations

ApiKeyAuth

X-API-KEYstringRequired

Path parameters

idstring · uuidRequired

The site ID

Query parameters

limitinteger · max: 500OptionalDefault: 100

min_impressionsintegerOptional

Filter queries with at least this many impressions

max_positionintegerOptional

Filter queries ranking at or above this position

sort_bystring · enumOptionalDefault: impressionsPossible values:

Responses

200

GSC query data

application/json

totalnumberOptional

gsc_connectedbooleanOptional

get

/v1/sites/{id}/gsc/queries

HTTPcURLJavaScriptPython

GET /v1/sites/{id}/gsc/queries HTTP/1.1
Host: api.cuppa.ai
X-API-KEY: YOUR_API_KEY
Accept: */*

200

GSC query data

{
  "queries": [
    {
      "query": "text",
      "page_url": "text",
      "clicks": 1,
      "impressions": 1,
      "ctr": 1,
      "position": 1,
      "opportunity_score": 1
    }
  ],
  "total": 1,
  "gsc_connected": true
}

Get brand context

get

Returns brand context (company info, competitors, keywords, etc.)

Authorizations

ApiKeyAuth

X-API-KEYstringRequired

Path parameters

idstring · uuidRequired

Site ID

Responses

200

Brand context

application/json

company_namestring · nullableOptional

descriptionstring · nullableOptional

Company/brand description

industrystring · nullableOptional

target_audiencestring · nullableOptional

value_propositionstring · nullableOptional

competitorsobject · nullableOptional

JSON object containing competitor information

ranking_keywordsobject · nullableOptional

JSON object containing keyword data

pain_pointsobject · nullableOptional

JSON object containing customer pain points

faq_questionsobject · nullableOptional

JSON object containing FAQ data

get

/v1/sites/{id}/brand/context

HTTPcURLJavaScriptPython

GET /v1/sites/{id}/brand/context HTTP/1.1
Host: api.cuppa.ai
X-API-KEY: YOUR_API_KEY
Accept: */*

200

Brand context

{
  "company_name": "text",
  "description": "text",
  "industry": "text",
  "target_audience": "text",
  "value_proposition": "text",
  "competitors": {},
  "ranking_keywords": {},
  "pain_points": {},
  "faq_questions": {}
}

Update brand context

patch

Update editable brand context fields. Creates context if it doesn't exist.

Authorizations

ApiKeyAuth

X-API-KEYstringRequired

Path parameters

idstring · uuidRequired

Site ID

Body

application/json

company_namestringOptional

descriptionstringOptional

taglinestringOptional

industrystringOptional

target_audiencestringOptional

value_propositionstringOptional

differentiatorsstring[]Optional

Responses

200

Brand context updated

application/json

company_namestring · nullableOptional

descriptionstring · nullableOptional

Company/brand description

industrystring · nullableOptional

target_audiencestring · nullableOptional

value_propositionstring · nullableOptional

competitorsobject · nullableOptional

JSON object containing competitor information

ranking_keywordsobject · nullableOptional

JSON object containing keyword data

pain_pointsobject · nullableOptional

JSON object containing customer pain points

faq_questionsobject · nullableOptional

JSON object containing FAQ data

patch

/v1/sites/{id}/brand/context

HTTPcURLJavaScriptPython

PATCH /v1/sites/{id}/brand/context HTTP/1.1
Host: api.cuppa.ai
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 158

{
  "company_name": "text",
  "description": "text",
  "tagline": "text",
  "industry": "text",
  "target_audience": "text",
  "value_proposition": "text",
  "differentiators": [
    "text"
  ]
}

200

Brand context updated

{
  "company_name": "text",
  "description": "text",
  "industry": "text",
  "target_audience": "text",
  "value_proposition": "text",
  "competitors": {},
  "ranking_keywords": {},
  "pain_points": {},
  "faq_questions": {}
}

Get brand visual style

get

Returns brand visual style (colors, fonts, logo, etc.)

Authorizations

ApiKeyAuth

X-API-KEYstringRequired

Path parameters

idstring · uuidRequired

Site ID

Responses

200

Brand visual style

application/json

logo_urlstring · nullableOptional

primary_colorstring · nullableOptional

secondary_colorstring · nullableOptional

accent_colorstring · nullableOptional

primary_fontstring · nullableOptional

visual_moodstring · nullableOptional

get

/v1/sites/{id}/brand/visual-style

HTTPcURLJavaScriptPython

GET /v1/sites/{id}/brand/visual-style HTTP/1.1
Host: api.cuppa.ai
X-API-KEY: YOUR_API_KEY
Accept: */*

200

Brand visual style

{
  "logo_url": "text",
  "primary_color": "text",
  "secondary_color": "text",
  "accent_color": "text",
  "primary_font": "text",
  "visual_mood": "text"
}

Update brand visual style

put

Update brand visual style. Only provided fields are updated.

Authorizations

ApiKeyAuth

X-API-KEYstringRequired

Path parameters

idstring · uuidRequired

Site ID

Body

application/json

logo_urlstringOptional

primary_colorstringOptional

secondary_colorstringOptional

accent_colorstringOptional

primary_fontstringOptional

secondary_fontstringOptional

visual_moodstringOptional

Responses

200

Brand visual style updated

application/json

logo_urlstring · nullableOptional

primary_colorstring · nullableOptional

secondary_colorstring · nullableOptional

accent_colorstring · nullableOptional

primary_fontstring · nullableOptional

visual_moodstring · nullableOptional

put

/v1/sites/{id}/brand/visual-style

HTTPcURLJavaScriptPython

PUT /v1/sites/{id}/brand/visual-style HTTP/1.1
Host: api.cuppa.ai
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 156

{
  "logo_url": "text",
  "primary_color": "text",
  "secondary_color": "text",
  "accent_color": "text",
  "primary_font": "text",
  "secondary_font": "text",
  "visual_mood": "text"
}

200

Brand visual style updated

{
  "logo_url": "text",
  "primary_color": "text",
  "secondary_color": "text",
  "accent_color": "text",
  "primary_font": "text",
  "visual_mood": "text"
}

Get brand voices

get

Returns brand voices (tone, persona, formality, etc.)

Authorizations

ApiKeyAuth

X-API-KEYstringRequired

Path parameters

idstring · uuidRequired

Site ID

Responses

200

List of brand voices

application/json

idstring · uuidOptional

namestringOptional

descriptionstring · nullableOptional

is_activebooleanOptional

valuesobjectOptional

JSON object containing voice parameters (tone, persona, formality, vocabulary_style, sentence_structure, etc.)

get

/v1/sites/{id}/brand/voices

HTTPcURLJavaScriptPython

GET /v1/sites/{id}/brand/voices HTTP/1.1
Host: api.cuppa.ai
X-API-KEY: YOUR_API_KEY
Accept: */*

200

List of brand voices

[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "text",
    "description": "text",
    "is_active": true,
    "values": {}
  }
]