Citera home
Browse documentation

Calendar

Calendar

Read a calendar, edit topics, cancel schedules, and reschedule publications.

Summarize with AIChatGPTClaudePerplexity

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

from, to

required, YYYY-MM-DD, ordered, inclusive window ≤ 93 days

limit

1–100, default 50

cursor

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

Required scope: calendar:read · Response: 200

: "${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}

Required scope: calendar:write · Response: 200

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

Required scope: calendar:write + publishing:write · Response: 200

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

Required scope: calendar:write · Response: 200

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}'