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

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-02-04T17:23:36.093Z",
    "updated_at": "2026-02-04T17:23:36.093Z"
  }
]

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

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-02-04T17:23:36.093Z",
  "updated_at": "2026-02-04T17:23:36.093Z"
}

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

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
}