Browse documentation
Read a calendar, edit topics, cancel schedules, and reschedule publications.
Product response envelope
Current product endpoints return a resource envelope: data.object, data.brand_id, data.page, and nested data.data containing the dashboard data. Pagination fields for these endpoints are inside data.data. Unknown measurements remain null; verified zeros remain 0. Sensitive values are redacted.
Write operations require the appropriate scopes on your key. Draft and calendar edits do not publish content. External effects require the confirmation rules described below.
GET …/calendar (calendar:read), operation get_calendar
Query | Rules |
|---|---|
| required, |
| 1–100, default 50 |
| offset |
data contains settings (stored settings or app defaults), topics (planning topics with generation and draft states, scheduled items and GitHub PR handoffs), orphan_publications (schedules not attached to a topic), truncated (the 1,000-row read cap was hit), from, to, has_more, next_cursor. A PR awaiting merge is not reported as published.
PATCH …/calendar/topics/{topic_id} (calendar:write), operation update_calendar_topic
Body: title (1–300), keyword (≤ 500), planned_date (YYYY-MM-DD, not in the past in the brand’s calendar timezone), plus optional optimistic-lock fields expected_title and expected_planned_date. Provide at least one of title/keyword/planned_date. Only ungenerated topics can be edited; after generation, edit the draft instead. Concurrent changes give 409 invalid_state, so refetch. Moving a topic does not swap other topics.
POST …/calendar/publications/{publication_id}/reschedule (calendar:write and publishing:write), operation reschedule_publication
Body: { "scheduled_at": "<future RFC 3339 with offset>", "user_timezone": "Europe/Stockholm", "confirm": true }. Requires api.publishing.enabled. Only scheduled publications can be moved. Costs 1 credit. The response includes planned_date and topic_date_synced; if that is false, refetch and reconcile before another edit.
POST …/calendar/publications/{publication_id}/cancel (calendar:write), operation cancel_publication
Body: { "confirm": true }. Works without an active subscription (recovery). Running or provider-accepted work cannot be rolled back.
Request examples
Choose a language for each endpoint. Set your assigned HTTPS API origin and environment variables, then replace the <placeholders>. These examples do not run requests in your browser.
GET/v1/brands/{brand_id}/calendar
: "${CITERA_API_BASE_URL:?Set CITERA_API_BASE_URL}"
: "${CITERA_API_KEY:?Set CITERA_API_KEY}"
: "${BRAND_ID:?Set BRAND_ID}"
: "${FROM_DATE:?Set FROM_DATE}"
: "${TO_DATE:?Set TO_DATE}"
curl --fail-with-body --connect-timeout 10 --max-time 30 -X GET "${CITERA_API_BASE_URL%/}/v1/brands/${BRAND_ID}/calendar?from=${FROM_DATE}&to=${TO_DATE}" \
-H "Accept: application/json" \
-H "Authorization: Bearer ${CITERA_API_KEY}"PATCH/v1/brands/{brand_id}/calendar/topics/{topic_id}
This is a write operation. Review the body and confirmation requirements before running it.
: "${CITERA_API_BASE_URL:?Set CITERA_API_BASE_URL}"
: "${CITERA_API_KEY:?Set CITERA_API_KEY}"
: "${BRAND_ID:?Set BRAND_ID}"
: "${TOPIC_ID:?Set TOPIC_ID}"
# Review this write and replace every <placeholder> before running.
curl --fail-with-body --connect-timeout 10 --max-time 30 -X PATCH "${CITERA_API_BASE_URL%/}/v1/brands/${BRAND_ID}/calendar/topics/${TOPIC_ID}" \
-H "Accept: application/json" \
-H "Authorization: Bearer ${CITERA_API_KEY}" \
-H "Content-Type: application/json" \
--data-raw '{"title":"Updated topic title","expected_title":"<current_title>"}'POST/v1/brands/{brand_id}/calendar/publications/{publication_id}/reschedule
This is a write operation. Review the body and confirmation requirements before running it.
: "${CITERA_API_BASE_URL:?Set CITERA_API_BASE_URL}"
: "${CITERA_API_KEY:?Set CITERA_API_KEY}"
: "${BRAND_ID:?Set BRAND_ID}"
: "${PUBLICATION_ID:?Set PUBLICATION_ID}"
# Review this write and replace every <placeholder> before running.
curl --fail-with-body --connect-timeout 10 --max-time 30 -X POST "${CITERA_API_BASE_URL%/}/v1/brands/${BRAND_ID}/calendar/publications/${PUBLICATION_ID}/reschedule" \
-H "Accept: application/json" \
-H "Authorization: Bearer ${CITERA_API_KEY}" \
-H "Content-Type: application/json" \
--data-raw '{"scheduled_at":"<future_RFC3339_with_offset>","user_timezone":"Europe/Stockholm","confirm":true}'POST/v1/brands/{brand_id}/calendar/publications/{publication_id}/cancel
This is a write operation. Review the body and confirmation requirements before running it.
: "${CITERA_API_BASE_URL:?Set CITERA_API_BASE_URL}"
: "${CITERA_API_KEY:?Set CITERA_API_KEY}"
: "${BRAND_ID:?Set BRAND_ID}"
: "${PUBLICATION_ID:?Set PUBLICATION_ID}"
# Review this write and replace every <placeholder> before running.
curl --fail-with-body --connect-timeout 10 --max-time 30 -X POST "${CITERA_API_BASE_URL%/}/v1/brands/${BRAND_ID}/calendar/publications/${PUBLICATION_ID}/cancel" \
-H "Accept: application/json" \
-H "Authorization: Bearer ${CITERA_API_KEY}" \
-H "Content-Type: application/json" \
--data-raw '{"confirm":true}'