# Planner

Content planning and scheduling

## List content planner items

> Returns scheduled content items. Requires Power plan or higher.

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Planner","description":"Content planning and scheduling"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"PlannerItem":{"type":"object","description":"Content planner item. Uses keyword_id as the unique identifier.","properties":{"keyword_id":{"type":"string","format":"uuid","description":"The unique identifier for this planner item (also the keyword ID)"},"site_id":{"type":"string","format":"uuid"},"cluster_id":{"type":"string","format":"uuid"},"date":{"type":"string","format":"date","description":"Scheduled date for content creation"},"status":{"type":"string","enum":["scheduled","progress","created","published"]},"keyword":{"type":"string","nullable":true,"description":"The keyword text"},"cluster_title":{"type":"string","nullable":true,"description":"Title of the parent cluster"},"metadata":{"type":"object","nullable":true,"description":"Additional metadata (may contain article_id after content is created)"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true}}}}},"paths":{"/v1/planner":{"get":{"summary":"List content planner items","description":"Returns scheduled content items. Requires Power plan or higher.","parameters":[{"in":"query","name":"page","schema":{"type":"integer"}},{"in":"query","name":"site","schema":{"type":"string","format":"uuid"}},{"in":"query","name":"status","schema":{"type":"string","enum":["scheduled","progress","created","published"]}},{"in":"query","name":"from_date","schema":{"type":"string","format":"date"},"description":"Filter items scheduled on or after this date"},{"in":"query","name":"to_date","schema":{"type":"string","format":"date"},"description":"Filter items scheduled on or before this date"}],"responses":{"200":{"description":"A list of planner items","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PlannerItem"}}}}}},"tags":["Planner"]}}}}
```

## Create a planner item

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

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Planner","description":"Content planning and scheduling"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"PlannerItem":{"type":"object","description":"Content planner item. Uses keyword_id as the unique identifier.","properties":{"keyword_id":{"type":"string","format":"uuid","description":"The unique identifier for this planner item (also the keyword ID)"},"site_id":{"type":"string","format":"uuid"},"cluster_id":{"type":"string","format":"uuid"},"date":{"type":"string","format":"date","description":"Scheduled date for content creation"},"status":{"type":"string","enum":["scheduled","progress","created","published"]},"keyword":{"type":"string","nullable":true,"description":"The keyword text"},"cluster_title":{"type":"string","nullable":true,"description":"Title of the parent cluster"},"metadata":{"type":"object","nullable":true,"description":"Additional metadata (may contain article_id after content is created)"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"}}}}}}},"paths":{"/v1/planner":{"post":{"summary":"Create a planner item","description":"Schedule a keyword for content creation. Each keyword can only be scheduled once.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["site_id","keyword_id","cluster_id","date"],"properties":{"site_id":{"type":"string","format":"uuid"},"keyword_id":{"type":"string","format":"uuid","description":"The keyword to schedule (must exist in site_keywords)"},"cluster_id":{"type":"string","format":"uuid","description":"The cluster this keyword belongs to"},"date":{"type":"string","format":"date","description":"Scheduled date for content creation"},"status":{"type":"string","enum":["scheduled","progress","created","published"],"default":"scheduled"}}}}}},"responses":{"201":{"description":"Planner item created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlannerItem"}}}},"409":{"description":"Planner item already exists for this keyword","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Planner"]}}}}
```

## Get a planner item

> Get a single planner item by keyword\_id. Requires Power plan or higher.

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Planner","description":"Content planning and scheduling"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"PlannerItem":{"type":"object","description":"Content planner item. Uses keyword_id as the unique identifier.","properties":{"keyword_id":{"type":"string","format":"uuid","description":"The unique identifier for this planner item (also the keyword ID)"},"site_id":{"type":"string","format":"uuid"},"cluster_id":{"type":"string","format":"uuid"},"date":{"type":"string","format":"date","description":"Scheduled date for content creation"},"status":{"type":"string","enum":["scheduled","progress","created","published"]},"keyword":{"type":"string","nullable":true,"description":"The keyword text"},"cluster_title":{"type":"string","nullable":true,"description":"Title of the parent cluster"},"metadata":{"type":"object","nullable":true,"description":"Additional metadata (may contain article_id after content is created)"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"}}}}}}},"paths":{"/v1/planner/{id}":{"get":{"summary":"Get a planner item","description":"Get a single planner item by keyword_id. Requires Power plan or higher.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"The keyword_id of the planner item"}],"responses":{"200":{"description":"The planner item","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlannerItem"}}}},"404":{"description":"Planner item not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Planner"]}}}}
```

## Update a planner item

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

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Planner","description":"Content planning and scheduling"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"PlannerItem":{"type":"object","description":"Content planner item. Uses keyword_id as the unique identifier.","properties":{"keyword_id":{"type":"string","format":"uuid","description":"The unique identifier for this planner item (also the keyword ID)"},"site_id":{"type":"string","format":"uuid"},"cluster_id":{"type":"string","format":"uuid"},"date":{"type":"string","format":"date","description":"Scheduled date for content creation"},"status":{"type":"string","enum":["scheduled","progress","created","published"]},"keyword":{"type":"string","nullable":true,"description":"The keyword text"},"cluster_title":{"type":"string","nullable":true,"description":"Title of the parent cluster"},"metadata":{"type":"object","nullable":true,"description":"Additional metadata (may contain article_id after content is created)"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"}}}}}}},"paths":{"/v1/planner/{id}":{"put":{"summary":"Update a planner item","description":"Update the scheduled date or status of a planner item. Requires Power plan or higher.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"The keyword_id of the planner item"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"New scheduled date"},"status":{"type":"string","enum":["scheduled","progress","created","published"],"description":"New status"}}}}}},"responses":{"200":{"description":"Planner item updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlannerItem"}}}},"400":{"description":"Invalid status transition","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Planner"]}}}}
```

## Delete a planner item

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

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Planner","description":"Content planning and scheduling"}],"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/planner/{id}":{"delete":{"summary":"Delete a planner item","description":"Remove a scheduled item from the content planner. Cannot delete created/published items. Requires Power plan or higher.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"The keyword_id of the planner item"}],"responses":{"200":{"description":"Planner item deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}},"400":{"description":"Cannot delete created or published items","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Planner"]}}}}
```

## Get unified content calendar

> Returns the unified content calendar showing all scheduled articles,\
> local pages, and social posts grouped by date. Requires Solo plan\
> or higher.<br>

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Planner","description":"Content planning and scheduling"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}}},"paths":{"/v1/planner/calendar":{"get":{"summary":"Get unified content calendar","description":"Returns the unified content calendar showing all scheduled articles,\nlocal pages, and social posts grouped by date. Requires Solo plan\nor higher.\n","parameters":[{"in":"query","name":"site_id","required":true,"schema":{"type":"string","format":"uuid"},"description":"Site/brand ID"},{"in":"query","name":"status","schema":{"type":"string","enum":["scheduled","created","published"]},"description":"Filter by status (default scheduled)"},{"in":"query","name":"from_date","schema":{"type":"string","format":"date"},"description":"Start date filter (YYYY-MM-DD)"},{"in":"query","name":"to_date","schema":{"type":"string","format":"date"},"description":"End date filter (YYYY-MM-DD)"}],"responses":{"200":{"description":"Unified content calendar","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"object","description":"Items grouped by date (YYYY-MM-DD keys)","additionalProperties":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["article","local","social_post"]},"id":{"type":"string"},"status":{"type":"string"}}}}},"counts":{"type":"object","properties":{"article":{"type":"integer"},"local":{"type":"integer"},"social_post":{"type":"integer"}}},"totalCount":{"type":"integer"}}}}}}},"tags":["Planner"]}}}}
```

## GET /v1/planner/events

> List planner events (holidays, custom dates, product launches)

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Planner","description":"Content planning and scheduling"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"PlannerEvent":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"team_id":{"type":"string","format":"uuid"},"site_id":{"type":"string","format":"uuid","nullable":true},"title":{"type":"string"},"description":{"type":"string","nullable":true},"event_date":{"type":"string","format":"date"},"event_type":{"type":"string","enum":["holiday","cultural","industry","custom","product_launch","seasonal"]},"recurrence":{"type":"string","enum":["none","annual","monthly","weekly"]},"source":{"type":"string","enum":["user","system","nager"]},"country_code":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"paths":{"/v1/planner/events":{"get":{"summary":"List planner events (holidays, custom dates, product launches)","parameters":[{"in":"query","name":"site_id","schema":{"type":"string","format":"uuid"},"description":"Filter by site ID"},{"in":"query","name":"from_date","schema":{"type":"string","format":"date"},"description":"Include events on or after this date"},{"in":"query","name":"to_date","schema":{"type":"string","format":"date"},"description":"Include events on or before this date"},{"in":"query","name":"event_type","schema":{"type":"string","enum":["holiday","cultural","industry","custom","product_launch","seasonal"]},"description":"Filter by event type"}],"responses":{"200":{"description":"A list of planner events","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PlannerEvent"}}}}}},"tags":["Planner"]}}}}
```

## POST /v1/planner/events

> Create a planner event

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Planner","description":"Content planning and scheduling"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"PlannerEvent":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"team_id":{"type":"string","format":"uuid"},"site_id":{"type":"string","format":"uuid","nullable":true},"title":{"type":"string"},"description":{"type":"string","nullable":true},"event_date":{"type":"string","format":"date"},"event_type":{"type":"string","enum":["holiday","cultural","industry","custom","product_launch","seasonal"]},"recurrence":{"type":"string","enum":["none","annual","monthly","weekly"]},"source":{"type":"string","enum":["user","system","nager"]},"country_code":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"paths":{"/v1/planner/events":{"post":{"summary":"Create a planner event","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title","event_date"],"properties":{"title":{"type":"string"},"event_date":{"type":"string","format":"date"},"site_id":{"type":"string","format":"uuid"},"description":{"type":"string"},"event_type":{"type":"string","enum":["holiday","cultural","industry","custom","product_launch","seasonal"]},"recurrence":{"type":"string","enum":["none","annual","monthly","weekly"]}}}}}},"responses":{"201":{"description":"Planner event created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlannerEvent"}}}}},"tags":["Planner"]}}}}
```

## GET /v1/planner/events/{id}

> Get a planner event by ID

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Planner","description":"Content planning and scheduling"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"PlannerEvent":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"team_id":{"type":"string","format":"uuid"},"site_id":{"type":"string","format":"uuid","nullable":true},"title":{"type":"string"},"description":{"type":"string","nullable":true},"event_date":{"type":"string","format":"date"},"event_type":{"type":"string","enum":["holiday","cultural","industry","custom","product_launch","seasonal"]},"recurrence":{"type":"string","enum":["none","annual","monthly","weekly"]},"source":{"type":"string","enum":["user","system","nager"]},"country_code":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"paths":{"/v1/planner/events/{id}":{"get":{"summary":"Get a planner event by ID","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Planner event","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlannerEvent"}}}}},"tags":["Planner"]}}}}
```

## DELETE /v1/planner/events/{id}

> Delete a planner event

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Planner","description":"Content planning and scheduling"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}}},"paths":{"/v1/planner/events/{id}":{"delete":{"summary":"Delete a planner event","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Planner event deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}}},"tags":["Planner"]}}}}
```

## PATCH /v1/planner/events/{id}

> Update a planner event

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Planner","description":"Content planning and scheduling"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"PlannerEvent":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"team_id":{"type":"string","format":"uuid"},"site_id":{"type":"string","format":"uuid","nullable":true},"title":{"type":"string"},"description":{"type":"string","nullable":true},"event_date":{"type":"string","format":"date"},"event_type":{"type":"string","enum":["holiday","cultural","industry","custom","product_launch","seasonal"]},"recurrence":{"type":"string","enum":["none","annual","monthly","weekly"]},"source":{"type":"string","enum":["user","system","nager"]},"country_code":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"paths":{"/v1/planner/events/{id}":{"patch":{"summary":"Update a planner event","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"event_date":{"type":"string","format":"date"},"event_type":{"type":"string","enum":["holiday","cultural","industry","custom","product_launch","seasonal"]},"recurrence":{"type":"string","enum":["none","annual","monthly","weekly"]},"metadata":{"type":"object"}}}}}},"responses":{"200":{"description":"Planner event updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlannerEvent"}}}}},"tags":["Planner"]}}}}
```


---

# 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/planner.md?ask=<question>
```

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.