Planner

Content planning and scheduling

List content planner items

get

Returns scheduled content items. Requires Power plan or higher.

Authorizations

ApiKeyAuth

X-API-KEYstringRequired

Query parameters

pageintegerOptional

sitestring · uuidOptional

statusstring · enumOptionalPossible values:

from_datestring · dateOptional

Filter items scheduled on or after this date

to_datestring · dateOptional

Filter items scheduled on or before this date

Responses

200

A list of planner items

application/json

get

/v1/planner

HTTPcURLJavaScriptPython

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

200

A list of planner items

[
  {
    "keyword_id": "123e4567-e89b-12d3-a456-426614174000",
    "site_id": "123e4567-e89b-12d3-a456-426614174000",
    "cluster_id": "123e4567-e89b-12d3-a456-426614174000",
    "date": "2026-02-04",
    "status": "scheduled",
    "keyword": "text",
    "cluster_title": "text",
    "metadata": {},
    "created_at": "2026-02-04T17:21:04.177Z",
    "updated_at": "2026-02-04T17:21:04.177Z"
  }
]

Create a planner item

post

Schedule a keyword for content creation. Each keyword can only be scheduled once.

Authorizations

ApiKeyAuth

X-API-KEYstringRequired

Body

application/json

site_idstring · uuidRequired

keyword_idstring · uuidRequired

The keyword to schedule (must exist in site_keywords)

cluster_idstring · uuidRequired

The cluster this keyword belongs to

datestring · dateRequired

Scheduled date for content creation

statusstring · enumOptionalDefault: scheduledPossible values:

Responses

201

Planner item created

application/json

409

Planner item already exists for this keyword

application/json

post

/v1/planner

HTTPcURLJavaScriptPython

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

{
  "site_id": "123e4567-e89b-12d3-a456-426614174000",
  "keyword_id": "123e4567-e89b-12d3-a456-426614174000",
  "cluster_id": "123e4567-e89b-12d3-a456-426614174000",
  "date": "2026-02-04",
  "status": "scheduled"
}

{
  "keyword_id": "123e4567-e89b-12d3-a456-426614174000",
  "site_id": "123e4567-e89b-12d3-a456-426614174000",
  "cluster_id": "123e4567-e89b-12d3-a456-426614174000",
  "date": "2026-02-04",
  "status": "scheduled",
  "keyword": "text",
  "cluster_title": "text",
  "metadata": {},
  "created_at": "2026-02-04T17:21:04.177Z",
  "updated_at": "2026-02-04T17:21:04.177Z"
}

Get a planner item

get

Get a single planner item by keyword_id. Requires Power plan or higher.

Authorizations

ApiKeyAuth

X-API-KEYstringRequired

Path parameters

idstring · uuidRequired

The keyword_id of the planner item

Responses

200

The planner item

application/json

404

Planner item not found

application/json

get

/v1/planner/{id}

HTTPcURLJavaScriptPython

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

{
  "keyword_id": "123e4567-e89b-12d3-a456-426614174000",
  "site_id": "123e4567-e89b-12d3-a456-426614174000",
  "cluster_id": "123e4567-e89b-12d3-a456-426614174000",
  "date": "2026-02-04",
  "status": "scheduled",
  "keyword": "text",
  "cluster_title": "text",
  "metadata": {},
  "created_at": "2026-02-04T17:21:04.177Z",
  "updated_at": "2026-02-04T17:21:04.177Z"
}

Update a planner item

put

Update the scheduled date or status of a planner item. Requires Power plan or higher.

Authorizations

ApiKeyAuth

X-API-KEYstringRequired

Path parameters

idstring · uuidRequired

The keyword_id of the planner item

Body

application/json

datestring · dateOptional

New scheduled date

statusstring · enumOptional

New status

Possible values:

Responses

200

Planner item updated

application/json

400

Invalid status transition

application/json

put

/v1/planner/{id}

HTTPcURLJavaScriptPython

PUT /v1/planner/{id} HTTP/1.1
Host: api.cuppa.ai
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 42

{
  "date": "2026-02-04",
  "status": "scheduled"
}

{
  "keyword_id": "123e4567-e89b-12d3-a456-426614174000",
  "site_id": "123e4567-e89b-12d3-a456-426614174000",
  "cluster_id": "123e4567-e89b-12d3-a456-426614174000",
  "date": "2026-02-04",
  "status": "scheduled",
  "keyword": "text",
  "cluster_title": "text",
  "metadata": {},
  "created_at": "2026-02-04T17:21:04.177Z",
  "updated_at": "2026-02-04T17:21:04.177Z"
}

Delete a planner item

delete

Remove a scheduled item from the content planner. Cannot delete created/published items. Requires Power plan or higher.

Authorizations

ApiKeyAuth

X-API-KEYstringRequired

Path parameters

idstring · uuidRequired

The keyword_id of the planner item

Responses

200

Planner item deleted

application/json

400

Cannot delete created or published items

application/json

delete

/v1/planner/{id}

HTTPcURLJavaScriptPython

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

{
  "success": true
}