# Sites
Site/brand management and Brand DNA
## List all sites/brands
> Returns a list of all sites (brands) for your team. Use site IDs when creating content to enable Brand DNA features.
```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Sites","description":"Site/brand management and Brand DNA"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"Site":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"domain":{"type":"string","description":"The domain/URL of the site"},"icon_url":{"type":"string","nullable":true,"description":"URL to the site favicon or icon"},"status":{"type":"string","enum":["active","inactive"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true}}}}},"paths":{"/v1/sites":{"get":{"summary":"List all sites/brands","description":"Returns a list of all sites (brands) for your team. Use site IDs when creating content to enable Brand DNA features.","parameters":[{"in":"query","name":"page","schema":{"type":"integer"},"description":"Page number for pagination"}],"responses":{"200":{"description":"A list of sites","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Site"}}}}}},"tags":["Sites"]}}}}
```
## Create a new site/brand
> 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.
```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Sites","description":"Site/brand management and Brand DNA"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"}}}}}}},"paths":{"/v1/sites":{"post":{"summary":"Create a new site/brand","description":"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.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["domain"],"properties":{"domain":{"type":"string","description":"The domain of the site (e.g., \"example.com\")"},"name":{"type":"string","description":"Optional display name for the brand"}}}}}},"responses":{"201":{"description":"Site created and Brand DNA queued","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"domain":{"type":"string"},"status":{"type":"string","enum":["queued"]},"message":{"type":"string"}}}}}},"409":{"description":"Site already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Sites"]}}}}
```
## GET /v1/sites/{id}
> Get a site by ID
```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Sites","description":"Site/brand management and Brand DNA"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"Site":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"domain":{"type":"string","description":"The domain/URL of the site"},"icon_url":{"type":"string","nullable":true,"description":"URL to the site favicon or icon"},"status":{"type":"string","enum":["active","inactive"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true}}}}},"paths":{"/v1/sites/{id}":{"get":{"summary":"Get a site by ID","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"The site ID"}],"responses":{"200":{"description":"The site object","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Site"}}}}},"tags":["Sites"]}}}}
```
## Get all brand information for a site
> Returns brand context, voices, and visual style in a single request.
```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Sites","description":"Site/brand management and Brand DNA"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"BrandContext":{"type":"object","properties":{"company_name":{"type":"string","nullable":true},"description":{"type":"string","nullable":true,"description":"Company/brand description"},"industry":{"type":"string","nullable":true},"target_audience":{"type":"string","nullable":true},"value_proposition":{"type":"string","nullable":true},"competitors":{"type":"object","nullable":true,"description":"JSON object containing competitor information"},"ranking_keywords":{"type":"object","nullable":true,"description":"JSON object containing keyword data"},"pain_points":{"type":"object","nullable":true,"description":"JSON object containing customer pain points"},"faq_questions":{"type":"object","nullable":true,"description":"JSON object containing FAQ data"}}},"BrandVoice":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"is_active":{"type":"boolean"},"values":{"type":"object","description":"JSON object containing voice parameters (tone, persona, formality, vocabulary_style, sentence_structure, etc.)"}}},"BrandVisualStyle":{"type":"object","properties":{"logo_url":{"type":"string","nullable":true},"primary_color":{"type":"string","nullable":true},"secondary_color":{"type":"string","nullable":true},"accent_color":{"type":"string","nullable":true},"primary_font":{"type":"string","nullable":true},"visual_mood":{"type":"string","nullable":true}}}}},"paths":{"/v1/sites/{id}/brand":{"get":{"summary":"Get all brand information for a site","description":"Returns brand context, voices, and visual style in a single request.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"The site ID"}],"responses":{"200":{"description":"Brand information","content":{"application/json":{"schema":{"type":"object","properties":{"context":{"$ref":"#/components/schemas/BrandContext"},"voices":{"type":"array","items":{"$ref":"#/components/schemas/BrandVoice"}},"visual_style":{"$ref":"#/components/schemas/BrandVisualStyle"}}}}}}},"tags":["Sites"]}}}}
```
## Get GSC search queries for a site
> Returns Google Search Console query data including clicks, impressions, position, and opportunity scores.\
> Requires Power plan or higher and GSC to be connected.
```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Sites","description":"Site/brand management and Brand DNA"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}}},"paths":{"/v1/sites/{id}/gsc/queries":{"get":{"summary":"Get GSC search queries for a site","description":"Returns Google Search Console query data including clicks, impressions, position, and opportunity scores.\nRequires Power plan or higher and GSC to be connected.\n","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"The site ID"},{"in":"query","name":"limit","schema":{"type":"integer","maximum":500,"default":100}},{"in":"query","name":"min_impressions","schema":{"type":"integer"},"description":"Filter queries with at least this many impressions"},{"in":"query","name":"max_position","schema":{"type":"integer"},"description":"Filter queries ranking at or above this position"},{"in":"query","name":"sort_by","schema":{"type":"string","enum":["position","impressions","clicks","opportunity_score"],"default":"impressions"}}],"responses":{"200":{"description":"GSC query data","content":{"application/json":{"schema":{"type":"object","properties":{"queries":{"type":"array","items":{"type":"object","properties":{"query":{"type":"string"},"page_url":{"type":"string","nullable":true},"clicks":{"type":"number"},"impressions":{"type":"number"},"ctr":{"type":"number"},"position":{"type":"number"},"opportunity_score":{"type":"number","nullable":true}}}},"total":{"type":"number"},"gsc_connected":{"type":"boolean"}}}}}}},"tags":["Sites"]}}}}
```
## Get brand context
> Returns brand context (company info, competitors, keywords, etc.)
```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Sites","description":"Site/brand management and Brand DNA"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"BrandContext":{"type":"object","properties":{"company_name":{"type":"string","nullable":true},"description":{"type":"string","nullable":true,"description":"Company/brand description"},"industry":{"type":"string","nullable":true},"target_audience":{"type":"string","nullable":true},"value_proposition":{"type":"string","nullable":true},"competitors":{"type":"object","nullable":true,"description":"JSON object containing competitor information"},"ranking_keywords":{"type":"object","nullable":true,"description":"JSON object containing keyword data"},"pain_points":{"type":"object","nullable":true,"description":"JSON object containing customer pain points"},"faq_questions":{"type":"object","nullable":true,"description":"JSON object containing FAQ data"}}}}},"paths":{"/v1/sites/{id}/brand/context":{"get":{"summary":"Get brand context","description":"Returns brand context (company info, competitors, keywords, etc.)","responses":{"200":{"description":"Brand context","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandContext"}}}}},"tags":["Sites"]}}}}
```
## Update brand context
> Update editable brand context fields. Creates context if it doesn't exist.
```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Sites","description":"Site/brand management and Brand DNA"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"BrandContext":{"type":"object","properties":{"company_name":{"type":"string","nullable":true},"description":{"type":"string","nullable":true,"description":"Company/brand description"},"industry":{"type":"string","nullable":true},"target_audience":{"type":"string","nullable":true},"value_proposition":{"type":"string","nullable":true},"competitors":{"type":"object","nullable":true,"description":"JSON object containing competitor information"},"ranking_keywords":{"type":"object","nullable":true,"description":"JSON object containing keyword data"},"pain_points":{"type":"object","nullable":true,"description":"JSON object containing customer pain points"},"faq_questions":{"type":"object","nullable":true,"description":"JSON object containing FAQ data"}}}}},"paths":{"/v1/sites/{id}/brand/context":{"patch":{"summary":"Update brand context","description":"Update editable brand context fields. Creates context if it doesn't exist.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"company_name":{"type":"string"},"description":{"type":"string"},"tagline":{"type":"string"},"industry":{"type":"string"},"target_audience":{"type":"string"},"value_proposition":{"type":"string"},"differentiators":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"Brand context updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandContext"}}}}},"tags":["Sites"]}}}}
```
## Get brand visual style
> Returns brand visual style (colors, fonts, logo, etc.)
```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Sites","description":"Site/brand management and Brand DNA"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"BrandVisualStyle":{"type":"object","properties":{"logo_url":{"type":"string","nullable":true},"primary_color":{"type":"string","nullable":true},"secondary_color":{"type":"string","nullable":true},"accent_color":{"type":"string","nullable":true},"primary_font":{"type":"string","nullable":true},"visual_mood":{"type":"string","nullable":true}}}}},"paths":{"/v1/sites/{id}/brand/visual-style":{"get":{"summary":"Get brand visual style","description":"Returns brand visual style (colors, fonts, logo, etc.)","responses":{"200":{"description":"Brand visual style","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandVisualStyle"}}}}},"tags":["Sites"]}}}}
```
## Update brand visual style
> Update brand visual style. Only provided fields are updated.
```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Sites","description":"Site/brand management and Brand DNA"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"BrandVisualStyle":{"type":"object","properties":{"logo_url":{"type":"string","nullable":true},"primary_color":{"type":"string","nullable":true},"secondary_color":{"type":"string","nullable":true},"accent_color":{"type":"string","nullable":true},"primary_font":{"type":"string","nullable":true},"visual_mood":{"type":"string","nullable":true}}}}},"paths":{"/v1/sites/{id}/brand/visual-style":{"put":{"summary":"Update brand visual style","description":"Update brand visual style. Only provided fields are updated.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"logo_url":{"type":"string"},"primary_color":{"type":"string"},"secondary_color":{"type":"string"},"accent_color":{"type":"string"},"primary_font":{"type":"string"},"secondary_font":{"type":"string"},"visual_mood":{"type":"string"}}}}}},"responses":{"200":{"description":"Brand visual style updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandVisualStyle"}}}}},"tags":["Sites"]}}}}
```
## Get brand voices
> Returns brand voices (tone, persona, formality, etc.)
```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Sites","description":"Site/brand management and Brand DNA"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"BrandVoice":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"is_active":{"type":"boolean"},"values":{"type":"object","description":"JSON object containing voice parameters (tone, persona, formality, vocabulary_style, sentence_structure, etc.)"}}}}},"paths":{"/v1/sites/{id}/brand/voices":{"get":{"summary":"Get brand voices","description":"Returns brand voices (tone, persona, formality, etc.)","responses":{"200":{"description":"List of brand voices","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BrandVoice"}}}}}},"tags":["Sites"]}}}}
```
## Get content strategy settings
> Returns the content strategy settings for a site including article\
> defaults, social publishing config, newsletter settings, and\
> automation rules. Requires Solo plan or higher.
```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Sites","description":"Site/brand management and Brand DNA"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"ContentStrategySettings":{"type":"object","description":"Content strategy settings for a site","properties":{"article_defaults":{"type":"object","properties":{"model":{"type":"string","description":"AI model for article generation"},"generate_meta_description":{"type":"boolean"},"generate_faq":{"type":"boolean"},"include_introduction":{"type":"boolean"},"include_conclusion":{"type":"boolean"},"generate_ai_images":{"type":"boolean"},"target_length":{"type":"string","enum":["short","medium","long","comprehensive"]},"extra_prompt":{"type":"string","nullable":true}}},"social_publishing":{"type":"object","properties":{"enabled":{"type":"boolean"},"auto_post_on_publish":{"type":"boolean"},"default_platforms":{"type":"array","items":{"type":"string"}},"default_tone":{"type":"string","enum":["professional","casual","humorous","educational","inspirational"]},"include_article_link":{"type":"boolean"},"include_hashtags":{"type":"boolean"},"max_hashtags":{"type":"integer"},"schedule_delay_minutes":{"type":"integer"},"generate_images":{"type":"boolean"}}},"newsletter":{"type":"object","properties":{"enabled":{"type":"boolean"},"cadence":{"type":"string","enum":["weekly","biweekly","monthly","none"]},"include_recent_articles":{"type":"boolean"},"max_articles_per_newsletter":{"type":"integer"},"send_day":{"type":"string","enum":["monday","tuesday","wednesday","thursday","friday","saturday","sunday"]},"send_hour":{"type":"integer"}}},"automation":{"type":"object","properties":{"planner_paused":{"type":"boolean"},"auto_schedule_from_clusters":{"type":"boolean"},"default_posts_per_week":{"type":"integer"},"preferred_publish_days":{"type":"array","items":{"type":"string"}},"preferred_publish_hour":{"type":"integer"},"auto_generate_social_on_publish":{"type":"boolean"},"auto_add_to_newsletter":{"type":"boolean"}}}}}}},"paths":{"/v1/sites/{id}/content-strategy":{"get":{"summary":"Get content strategy settings","description":"Returns the content strategy settings for a site including article\ndefaults, social publishing config, newsletter settings, and\nautomation rules. Requires Solo plan or higher.\n","responses":{"200":{"description":"Content strategy settings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentStrategySettings"}}}}},"tags":["Sites"]}}}}
```
## Update content strategy settings
> Update content strategy settings for a site. Supports partial\
> updates: only send the sections you want to change. Requires\
> Solo plan or higher.
```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Sites","description":"Site/brand management and Brand DNA"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"ContentStrategySettings":{"type":"object","description":"Content strategy settings for a site","properties":{"article_defaults":{"type":"object","properties":{"model":{"type":"string","description":"AI model for article generation"},"generate_meta_description":{"type":"boolean"},"generate_faq":{"type":"boolean"},"include_introduction":{"type":"boolean"},"include_conclusion":{"type":"boolean"},"generate_ai_images":{"type":"boolean"},"target_length":{"type":"string","enum":["short","medium","long","comprehensive"]},"extra_prompt":{"type":"string","nullable":true}}},"social_publishing":{"type":"object","properties":{"enabled":{"type":"boolean"},"auto_post_on_publish":{"type":"boolean"},"default_platforms":{"type":"array","items":{"type":"string"}},"default_tone":{"type":"string","enum":["professional","casual","humorous","educational","inspirational"]},"include_article_link":{"type":"boolean"},"include_hashtags":{"type":"boolean"},"max_hashtags":{"type":"integer"},"schedule_delay_minutes":{"type":"integer"},"generate_images":{"type":"boolean"}}},"newsletter":{"type":"object","properties":{"enabled":{"type":"boolean"},"cadence":{"type":"string","enum":["weekly","biweekly","monthly","none"]},"include_recent_articles":{"type":"boolean"},"max_articles_per_newsletter":{"type":"integer"},"send_day":{"type":"string","enum":["monday","tuesday","wednesday","thursday","friday","saturday","sunday"]},"send_hour":{"type":"integer"}}},"automation":{"type":"object","properties":{"planner_paused":{"type":"boolean"},"auto_schedule_from_clusters":{"type":"boolean"},"default_posts_per_week":{"type":"integer"},"preferred_publish_days":{"type":"array","items":{"type":"string"}},"preferred_publish_hour":{"type":"integer"},"auto_generate_social_on_publish":{"type":"boolean"},"auto_add_to_newsletter":{"type":"boolean"}}}}}}},"paths":{"/v1/sites/{id}/content-strategy":{"put":{"summary":"Update content strategy settings","description":"Update content strategy settings for a site. Supports partial\nupdates: only send the sections you want to change. Requires\nSolo plan or higher.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentStrategySettings"}}}},"responses":{"200":{"description":"Updated content strategy settings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentStrategySettings"}}}}},"tags":["Sites"]}}}}
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://learn.cuppa.ai/rest-api/sites.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.