Skip to main content

Read and write a show’s Content Calendar content items over REST

Premium Advanced Content Calendar

The routes behind the Calendar screen: GET and POST /benecaster-content-calendar/v1/shows/{show_id}/items, GET, PUT, PATCH and DELETE …/shows/{show_id}/items/{id}, and GET …/shows/{show_id}/episodes.

Access. Every route needs manage_options and the REST nonce (send an X-WP-Nonce for wp_rest; wp.apiFetch does this for you), and Content Calendar switched on for {show_id}, else 403 benecaster_content_calendar_off_for_show. An item on another show answers 404 benecaster_content_calendar_item_not_found, exactly like one that does not exist.

Listing. GET …/items needs from and to (YYYY-MM-DD, both included, at most 100 days apart, else 400 benecaster_content_calendar_bad_range). It answers { items: [item] }: every item that publishes or is due in the range, by publish date, all-day before timed. Items whose type the show has switched off are left out.

An item has the fields listed in Run your own code when a Content Calendar content item is saved or deleted, minus created_by, created_at and updated_at, plus fields ready to show:

  • type_label: the show’s name for the type, or the typed Other name; Other for a type the show no longer has.
  • type_color: #rrggbb.
  • publish_time_label and due_time_label: the times in the site’s Time Format, or null.
  • attachment: { id, url, title, filename }, or null when there is none or it left the media library.
  • episode: { id, title, status }, or null when there is none or it is in the Trash.

To add keys of your own to each item, use benecaster_content_calendar_item_response.

Writing. A write sends every field:

  • type: a switched-on type of the show other than episode. An item being edited may keep its current type.
  • type_name: Other only, 1–60 characters.
  • title: 1–200 characters.
  • publish_date (required) and publish_time (HH:MM or '').
  • due_date ('' for none; not after the publish date or, on the same day, its time) and due_time.
  • status, with cancel_reason (up to 5,000 characters) required for canceled.
  • content: kept only for a type with content text, up to the type’s limit, counted in characters.
  • reference_url: http or https, up to 2,048 characters.
  • attachment_id: a media-library attachment, or 0.
  • promotion_notes (up to 5,000 characters), call_to_action (up to 500) and notes (up to 5,000).
  • episode_id: 0, or an episode of this show that is not in the Trash.

Answers. A refused field is 400 benecaster_content_calendar_invalid_item, with data.field naming it. POST answers 201. Linking an episode adds the episode note Calendar event added: [type] on [publish date]. …/episodes answers { items: [ { id, title, status } ] }: the show’s newest 200 episodes, drafts included. Add _locale=user to have the messages and the note in the user’s language.

Code

await apiFetch( {
    path: `/benecaster-content-calendar/v1/shows/${ showId }/items`,
    method: 'POST',
    data: {
        type: 'tweet', type_name: '', title: 'Teaser clip', status: 'planned',
        publish_date: '2026-12-04', publish_time: '09:00', due_date: '2026-12-01', due_time: '',
        cancel_reason: '', content: 'New episode Friday', reference_url: '', attachment_id: 0,
        promotion_notes: '', call_to_action: 'Listen now', notes: '', episode_id: 0,
    },
} );

View on GitHub →

Need this built rather than just documented? See our services →