Clusters

Keyword cluster management

Generate a content cluster

post

Create an interlinked content cluster with a pillar article and supporting articles. All articles are automatically interlinked using Link Engine. Requires Power plan or higher and Link Engine to be configured.

Authorizations

ApiKeyAuth

X-API-KEYstringRequired

Body

application/json

site_idstring · uuidRequired

pillar_keywordstring · max: 200Required

The main topic/keyword for the pillar article

pillar_titlestring · max: 200Optional

Optional custom title for pillar article

pillar_secondary_keywordsstring[] · max: 5Optional

supporting_keywordsstring[] · min: 1 · max: 10Required

Keywords for supporting articles that link to the pillar

Responses

202

Cluster generation started

application/json

post

/v1/clusters/generate

HTTPcURLJavaScriptPython

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

{
  "site_id": "123e4567-e89b-12d3-a456-426614174000",
  "pillar_keyword": "text",
  "pillar_title": "text",
  "pillar_secondary_keywords": [
    "text"
  ],
  "supporting_keywords": [
    "text"
  ],
  "options": {
    "article_type": "general",
    "word_count": 1,
    "language": "text",
    "model": "text"
  }
}

202

Cluster generation started

{
  "cluster_id": "text",
  "total_articles": 1,
  "status": "queued",
  "message": "text"
}

List keyword clusters

get

Returns keyword clusters for content planning. Requires Power plan or higher.

Authorizations

ApiKeyAuth

X-API-KEYstringRequired

Query parameters

pageintegerOptional

sitestring · uuidOptional

Filter by site ID

in_planbooleanOptional

Filter by active clusters

Responses

200

A list of clusters

application/json

idstring · uuidOptional

site_idstring · uuidOptional

titlestringOptional

descriptionstring · nullableOptional

in_planbooleanOptional

Whether this cluster is active in content planning

pillar_pagestring · nullableOptional

URL of the pillar page for this cluster

total_keywordsintegerOptional

total_search_volumeintegerOptional

created_atstring · date-timeOptional

updated_atstring · date-time · nullableOptional

get

/v1/clusters

HTTPcURLJavaScriptPython

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

200

A list of clusters

[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "site_id": "123e4567-e89b-12d3-a456-426614174000",
    "title": "text",
    "description": "text",
    "in_plan": true,
    "pillar_page": "text",
    "total_keywords": 1,
    "total_search_volume": 1,
    "created_at": "2026-03-22T03:46:23.825Z",
    "updated_at": "2026-03-22T03:46:23.825Z"
  }
]

Get a cluster with keywords

get

Authorizations

ApiKeyAuth

X-API-KEYstringRequired

Path parameters

idstring · uuidRequired

The cluster ID

Responses

200

Cluster with keywords

application/json

idstring · uuidOptional

site_idstring · uuidOptional

titlestringOptional

descriptionstring · nullableOptional

in_planbooleanOptional

Whether this cluster is active in content planning

pillar_pagestring · nullableOptional

URL of the pillar page for this cluster

total_keywordsintegerOptional

total_search_volumeintegerOptional

created_atstring · date-timeOptional

updated_atstring · date-time · nullableOptional

get

/v1/clusters/{id}

HTTPcURLJavaScriptPython

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

200

Cluster with keywords

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "site_id": "123e4567-e89b-12d3-a456-426614174000",
  "title": "text",
  "description": "text",
  "in_plan": true,
  "pillar_page": "text",
  "total_keywords": 1,
  "total_search_volume": 1,
  "created_at": "2026-03-22T03:46:23.825Z",
  "updated_at": "2026-03-22T03:46:23.825Z",
  "keywords": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "keyword": "text",
      "search_volume": 1,
      "keyword_difficulty": 1,
      "cpc": 1,
      "search_intent": "text",
      "article_id": "text"
    }
  ]
}

Activate a cluster

post

Mark a cluster as "In Plan" for content planning. Requires Power plan or higher.

Authorizations

ApiKeyAuth

X-API-KEYstringRequired

Path parameters

idstring · uuidRequired

The cluster ID

Responses

200

Cluster activated

application/json

idstring · uuidOptional

site_idstring · uuidOptional

titlestringOptional

descriptionstring · nullableOptional

in_planbooleanOptional

Whether this cluster is active in content planning

pillar_pagestring · nullableOptional

URL of the pillar page for this cluster

total_keywordsintegerOptional

total_search_volumeintegerOptional

created_atstring · date-timeOptional

updated_atstring · date-time · nullableOptional

post

/v1/clusters/{id}/activate

HTTPcURLJavaScriptPython

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

200

Cluster activated

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "site_id": "123e4567-e89b-12d3-a456-426614174000",
  "title": "text",
  "description": "text",
  "in_plan": true,
  "pillar_page": "text",
  "total_keywords": 1,
  "total_search_volume": 1,
  "created_at": "2026-03-22T03:46:23.825Z",
  "updated_at": "2026-03-22T03:46:23.825Z"
}

Deactivate a cluster

post

Remove a cluster from "In Plan". Requires Power plan or higher.

Authorizations

ApiKeyAuth

X-API-KEYstringRequired

Path parameters

idstring · uuidRequired

The cluster ID

Responses

200

Cluster deactivated

application/json

idstring · uuidOptional

site_idstring · uuidOptional

titlestringOptional

descriptionstring · nullableOptional

in_planbooleanOptional

Whether this cluster is active in content planning

pillar_pagestring · nullableOptional

URL of the pillar page for this cluster

total_keywordsintegerOptional

total_search_volumeintegerOptional

created_atstring · date-timeOptional

updated_atstring · date-time · nullableOptional

post

/v1/clusters/{id}/deactivate

HTTPcURLJavaScriptPython

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

200

Cluster deactivated

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "site_id": "123e4567-e89b-12d3-a456-426614174000",
  "title": "text",
  "description": "text",
  "in_plan": true,
  "pillar_page": "text",
  "total_keywords": 1,
  "total_search_volume": 1,
  "created_at": "2026-03-22T03:46:23.825Z",
  "updated_at": "2026-03-22T03:46:23.825Z"
}