Editorial
The publication rules of one website, the backlog of what it means to write about, and the rolling calendar that turns the two into dated drafts. editorial_plan is a singleton that always exists, :refill fills the calendar on demand, and a slot becomes a post with :materialize and goes live with :publish.
Get editorial_plan
The publication rules of one website's editorial desk: on which days and at what local times posts go out, how far ahead the calendar is filled, how long before its date a slot becomes a draft, and what that draft inherits. There is one per website and it always exists — a website that has never configured one reads back the defaults, and the first Update is what stores it. What to write about lives in editorial_topics, and when each piece goes out in editorial_slots.
path Parameters
website_idId of the parent website.
Headers
If-None-MatchA matching etag answers 304 with no body (§16).
Get editorial_plan › Responses
The resource.
nameThe resource name (§5) — the identity of this resource, and the path that addresses it: websites/{website}/cms_pages/{cms_page}. It is the handle to store, not a human label.
create_timeWhen the resource was created (RFC 3339, UTC).
update_timeWhen the resource last changed (RFC 3339, UTC).
etagVersion of the persisted state. Send it back in If-Match on Update or Delete and the write is rejected with ABORTED if anyone else changed the resource meanwhile (§14).
enabledWhether the desk is running. While it is false the calendar is not filled, no draft is prepared and nothing wakes up — the plan is kept, not executed.
time_zoneThe IANA zone the schedule's wall-clock times are read in, so "Monday 10:00" stays 10:00 across a daylight-saving change instead of drifting an hour twice a year.
scheduleWhen posts go out, as a list of {"weekday", "time_of_day"} rules. weekday is one of MONDAY…SUNDAY and time_of_day is a local HH:MM. An empty list plans nothing.
planning_horizon_daysHow far ahead the calendar is filled, in days. The window rolls forward on its own, so a plan left alone always has about this much scheduled. Defaults to 30.
draft_lead_daysHow long before its date a slot turns into a draft, in days — the writing time the desk gives itself. Defaults to 3.
target_typeWhat kind of content a slot produces. blog_post is the only kind this platform makes today, and the default; a slot may name a different one of its own.
content_modeWho fills a slot when its date comes near. EMPTY_DRAFT — the default — creates the draft and leaves the writing to a person; other modes are offered by the platform's producers, and a mode this website is not set up for is refused. A slot may override it for one date.
default_category_idsThe blog_categories a fresh draft is filed under when its topic names none of its own.
default_tag_idsThe blog_tags a fresh draft carries when its topic names none of its own.
default_author_idsThe blog_authors a fresh draft is credited to when its topic names no author of its own: one of them, chosen at random for each slot and kept if that slot is drafted again. List one author to credit every such draft to them.
notification_emailsWho the desk writes to about its work, up to 20 addresses. They are stored trimmed and in lower case, without repeats. Left empty, the letters go to the owner of the account.
notification_eventsWhat the desk writes about: TOPICS_PROPOSED — new topics were suggested, ARTICLE_DRAFTED — a draft is ready, ARTICLE_PUBLISHED — an article went live, FAILURE — preparing or publishing an article failed, or the desk is held back. Never set, it is all four. An empty list turns the letters off.
next_tick_timeWhen the desk next looks at this website's calendar. It is the plan's liveness signal: a value in the past on an enabled plan means the schedule stalled and needs waking.
Update editorial_plan
Reads the desk's rules. A website that has never configured one gets the defaults back — the desk switched off, UTC, no schedule, a 30-day horizon and 3 days of writing time — rather than a 404: there is exactly one plan per website and it always exists, implicitly.
next_tick_time says when the desk next looks at this calendar. On an enabled plan a value in the past means the schedule has stalled.
path Parameters
website_idId of the parent website.
query Parameters
update_maskComma-separated field paths to merge. A field named here and sent as null is cleared; without the mask a null is dropped (§7, §11).
Headers
If-MatchThe etag the client last read. A mismatch is ABORTED (409) with the current resource in the error details (§14).
Update editorial_plan › Request Body
enabledWhether the desk is running. While it is false the calendar is not filled, no draft is prepared and nothing wakes up — the plan is kept, not executed.
time_zoneThe IANA zone the schedule's wall-clock times are read in, so "Monday 10:00" stays 10:00 across a daylight-saving change instead of drifting an hour twice a year.
scheduleWhen posts go out, as a list of {"weekday", "time_of_day"} rules. weekday is one of MONDAY…SUNDAY and time_of_day is a local HH:MM. An empty list plans nothing.
planning_horizon_daysHow far ahead the calendar is filled, in days. The window rolls forward on its own, so a plan left alone always has about this much scheduled. Defaults to 30.
draft_lead_daysHow long before its date a slot turns into a draft, in days — the writing time the desk gives itself. Defaults to 3.
target_typeWhat kind of content a slot produces. blog_post is the only kind this platform makes today, and the default; a slot may name a different one of its own.
content_modeWho fills a slot when its date comes near. EMPTY_DRAFT — the default — creates the draft and leaves the writing to a person; other modes are offered by the platform's producers, and a mode this website is not set up for is refused. A slot may override it for one date.
default_category_idsThe blog_categories a fresh draft is filed under when its topic names none of its own.
default_tag_idsThe blog_tags a fresh draft carries when its topic names none of its own.
default_author_idsThe blog_authors a fresh draft is credited to when its topic names no author of its own: one of them, chosen at random for each slot and kept if that slot is drafted again. List one author to credit every such draft to them.
notification_emailsWho the desk writes to about its work, up to 20 addresses. They are stored trimmed and in lower case, without repeats. Left empty, the letters go to the owner of the account.
notification_eventsWhat the desk writes about: TOPICS_PROPOSED — new topics were suggested, ARTICLE_DRAFTED — a draft is ready, ARTICLE_PUBLISHED — an article went live, FAILURE — preparing or publishing an article failed, or the desk is held back. Never set, it is all four. An empty list turns the letters off.
Update editorial_plan › Responses
The updated resource.
nameThe resource name (§5) — the identity of this resource, and the path that addresses it: websites/{website}/cms_pages/{cms_page}. It is the handle to store, not a human label.
create_timeWhen the resource was created (RFC 3339, UTC).
update_timeWhen the resource last changed (RFC 3339, UTC).
etagVersion of the persisted state. Send it back in If-Match on Update or Delete and the write is rejected with ABORTED if anyone else changed the resource meanwhile (§14).
enabledWhether the desk is running. While it is false the calendar is not filled, no draft is prepared and nothing wakes up — the plan is kept, not executed.
time_zoneThe IANA zone the schedule's wall-clock times are read in, so "Monday 10:00" stays 10:00 across a daylight-saving change instead of drifting an hour twice a year.
scheduleWhen posts go out, as a list of {"weekday", "time_of_day"} rules. weekday is one of MONDAY…SUNDAY and time_of_day is a local HH:MM. An empty list plans nothing.
planning_horizon_daysHow far ahead the calendar is filled, in days. The window rolls forward on its own, so a plan left alone always has about this much scheduled. Defaults to 30.
draft_lead_daysHow long before its date a slot turns into a draft, in days — the writing time the desk gives itself. Defaults to 3.
target_typeWhat kind of content a slot produces. blog_post is the only kind this platform makes today, and the default; a slot may name a different one of its own.
content_modeWho fills a slot when its date comes near. EMPTY_DRAFT — the default — creates the draft and leaves the writing to a person; other modes are offered by the platform's producers, and a mode this website is not set up for is refused. A slot may override it for one date.
default_category_idsThe blog_categories a fresh draft is filed under when its topic names none of its own.
default_tag_idsThe blog_tags a fresh draft carries when its topic names none of its own.
default_author_idsThe blog_authors a fresh draft is credited to when its topic names no author of its own: one of them, chosen at random for each slot and kept if that slot is drafted again. List one author to credit every such draft to them.
notification_emailsWho the desk writes to about its work, up to 20 addresses. They are stored trimmed and in lower case, without repeats. Left empty, the letters go to the owner of the account.
notification_eventsWhat the desk writes about: TOPICS_PROPOSED — new topics were suggested, ARTICLE_DRAFTED — a draft is ready, ARTICLE_PUBLISHED — an article went live, FAILURE — preparing or publishing an article failed, or the desk is held back. Never set, it is all four. An empty list turns the letters off.
next_tick_timeWhen the desk next looks at this website's calendar. It is the plan's liveness signal: a value in the past on an enabled plan means the schedule stalled and needs waking.
Refill (editorial_plan)
Fills the calendar up to the horizon now, instead of waiting for the desk to get to it. Slots are created on every scheduled moment that has none, taking topics off the backlog in priority order; a moment that already has a slot is left alone, including one that was skipped.
Safe to repeat — running it twice over unchanged data creates nothing. It answers with the plan; what it actually created is in editorial_slots. If the backlog runs dry the calendar is simply left part-filled, which is a state to show rather than an error.
path Parameters
website_idId of the parent website.
Refill (editorial_plan) › Request Body optional
Refill (editorial_plan) › Responses
The affected resource, or the method’s own response object (§10).
List editorial_slots
One cell of the content calendar: a moment, the topic that fills it, and the content it produced. A slot is created by the desk from the plan's schedule, or by hand for a date you want yourself. Its moment is unique, which is how a date you chose is never overwritten — the desk simply never plans on a taken moment. :skip drops the date and returns its topic to the backlog, :materialize prepares the draft now rather than waiting, and :publish makes that draft live.
path Parameters
website_idId of the parent website.
query Parameters
page_sizeRows per page. Over the maximum is clamped, not rejected.
page_tokenOpaque token from a previous next_page_token. A token minted under a different order_by/filter is rejected.
skipRows to skip before the page (AIP-158). skip + page_size is capped at 10000; beyond that is OUT_OF_RANGE.
order_byComma-separated field [asc|desc], at most 3 keys. Default: scheduled_time asc. Sortable: scheduled_time.
filterAIP-160 subset (§8). Filterable: origin, review_verdict, scheduled_time, status, target_id, target_type, title, topic_id. A field outside the list is INVALID_ARGUMENT.
List editorial_slots › Responses
One page of editorial_slots.
This page of editorial_slots, in the requested order.
next_page_tokenOpaque. Absent or empty means this was the last page.
total_sizeRows in the whole filtered collection, not in this page.
Create editorial_slot
Puts your own piece on a date, instead of waiting for the desk to plan one. Send at least a scheduled_time; name a topic_id to take an idea off the backlog, or just a title to schedule something that was never on it.
A moment carries one slot, so a date that already has one answers ALREADY_EXISTS — edit the slot that is there rather than adding a second. A slot created here belongs to you from then on: the desk never plans over it and never changes it.
path Parameters
website_idId of the parent website.
Create editorial_slot › Request Body
scheduled_timeWhen this piece goes out. Unique across the website — one slot per moment — and the order the calendar is read in. Moving a slot is a write of this field, and it takes the slot out of the desk's hands.
topic_idThe editorial_topics resource filling this slot. Empty on a slot someone put on the calendar with a title and no backlog entry.
titleThe headline this slot stands for, copied from its topic when the slot was made. It is a snapshot, so a month of calendar draws without reading every topic — and so a topic renamed later does not rewrite a slot that already produced a draft.
target_typeWhat this slot produces. Defaults to the plan's and cannot be changed afterwards: a slot that switched kind mid-flight would leave its draft behind with nothing pointing at it.
content_modeWho fills this one slot, overriding the plan's content_mode for this date alone — "I am writing this Friday myself". Absent, the plan decides. It can be set while the slot is still PLANNED or FAILED, not once its draft exists.
Create editorial_slot › Responses
The created resource.
nameThe resource name (§5) — the identity of this resource, and the path that addresses it: websites/{website}/cms_pages/{cms_page}. It is the handle to store, not a human label.
idThe last segment of name on its own, for a client that needs to build a child URL. Unique inside its parent, never across the platform.
create_timeWhen the resource was created (RFC 3339, UTC).
update_timeWhen the resource last changed (RFC 3339, UTC).
etagVersion of the persisted state. Send it back in If-Match on Update or Delete and the write is rejected with ABORTED if anyone else changed the resource meanwhile (§14).
scheduled_timeWhen this piece goes out. Unique across the website — one slot per moment — and the order the calendar is read in. Moving a slot is a write of this field, and it takes the slot out of the desk's hands.
topic_idThe editorial_topics resource filling this slot. Empty on a slot someone put on the calendar with a title and no backlog entry.
titleThe headline this slot stands for, copied from its topic when the slot was made. It is a snapshot, so a month of calendar draws without reading every topic — and so a topic renamed later does not rewrite a slot that already produced a draft.
target_typeWhat this slot produces. Defaults to the plan's and cannot be changed afterwards: a slot that switched kind mid-flight would leave its draft behind with nothing pointing at it.
target_idThe blog_posts resource this slot created. It is also what makes preparing a draft safe to repeat — a slot that already names its post never gets a second one.
statusWhere the slot stands: PLANNED before its draft exists, GENERATING while a producer is writing it, DRAFTED once it does, PUBLISHED once that post is live, SKIPPED if the date was dropped, FAILED if preparing the draft did not work. FAILED is retried where the retry is free, and left to you where it is not.
originAUTO while the slot is the desk's to manage, MANUAL once a person created or edited it — after which the desk leaves it alone for good. This is the whole of "a person outranks the schedule".
last_errorWhy the last attempt to prepare this slot's draft did not work. Cleared as soon as one succeeds, so it always describes the present.
content_modeWho fills this one slot, overriding the plan's content_mode for this date alone — "I am writing this Friday myself". Absent, the plan decides. It can be set while the slot is still PLANNED or FAILED, not once its draft exists.
generation_idThe latest editorial_generations run producing this slot's content, when a producer other than a person is writing it. Absent on a slot nobody generated.
review_verdictWhat the producer's own check made of the content: PASSED, or NEEDS_REVIEW when a person should read it before it goes out. A snapshot of the run's verdict, kept here so a month of calendar draws its badges without reading every run.
Get editorial_slot
One cell of the content calendar: a moment, the topic that fills it, and the content it produced. A slot is created by the desk from the plan's schedule, or by hand for a date you want yourself. Its moment is unique, which is how a date you chose is never overwritten — the desk simply never plans on a taken moment. :skip drops the date and returns its topic to the backlog, :materialize prepares the draft now rather than waiting, and :publish makes that draft live.
path Parameters
website_idId of the parent website.
editorial_slot_idId of the parent editorial_slot.
Headers
If-None-MatchA matching etag answers 304 with no body (§16).
Get editorial_slot › Responses
The resource.
nameThe resource name (§5) — the identity of this resource, and the path that addresses it: websites/{website}/cms_pages/{cms_page}. It is the handle to store, not a human label.
idThe last segment of name on its own, for a client that needs to build a child URL. Unique inside its parent, never across the platform.
create_timeWhen the resource was created (RFC 3339, UTC).
update_timeWhen the resource last changed (RFC 3339, UTC).
etagVersion of the persisted state. Send it back in If-Match on Update or Delete and the write is rejected with ABORTED if anyone else changed the resource meanwhile (§14).
scheduled_timeWhen this piece goes out. Unique across the website — one slot per moment — and the order the calendar is read in. Moving a slot is a write of this field, and it takes the slot out of the desk's hands.
topic_idThe editorial_topics resource filling this slot. Empty on a slot someone put on the calendar with a title and no backlog entry.
titleThe headline this slot stands for, copied from its topic when the slot was made. It is a snapshot, so a month of calendar draws without reading every topic — and so a topic renamed later does not rewrite a slot that already produced a draft.
target_typeWhat this slot produces. Defaults to the plan's and cannot be changed afterwards: a slot that switched kind mid-flight would leave its draft behind with nothing pointing at it.
target_idThe blog_posts resource this slot created. It is also what makes preparing a draft safe to repeat — a slot that already names its post never gets a second one.
statusWhere the slot stands: PLANNED before its draft exists, GENERATING while a producer is writing it, DRAFTED once it does, PUBLISHED once that post is live, SKIPPED if the date was dropped, FAILED if preparing the draft did not work. FAILED is retried where the retry is free, and left to you where it is not.
originAUTO while the slot is the desk's to manage, MANUAL once a person created or edited it — after which the desk leaves it alone for good. This is the whole of "a person outranks the schedule".
last_errorWhy the last attempt to prepare this slot's draft did not work. Cleared as soon as one succeeds, so it always describes the present.
content_modeWho fills this one slot, overriding the plan's content_mode for this date alone — "I am writing this Friday myself". Absent, the plan decides. It can be set while the slot is still PLANNED or FAILED, not once its draft exists.
generation_idThe latest editorial_generations run producing this slot's content, when a producer other than a person is writing it. Absent on a slot nobody generated.
review_verdictWhat the producer's own check made of the content: PASSED, or NEEDS_REVIEW when a person should read it before it goes out. A snapshot of the run's verdict, kept here so a month of calendar draws its badges without reading every run.
Delete editorial_slot
Removes the date from the calendar. Its topic goes back to the backlog, and any draft it already produced is left alone — that is a post with a life of its own, and dropping a calendar cell is not a reason to delete somebody's article.
Deleting frees the moment, so the desk may plan something else there. To keep a date deliberately empty, use :skip instead.
path Parameters
website_idId of the parent website.
editorial_slot_idId of the parent editorial_slot.
Headers
If-MatchThe etag the client last read. A mismatch is ABORTED (409) with the current resource in the error details (§14).
Delete editorial_slot › Responses
Deleted. No body (§7).
Update editorial_slot
Moves a slot, or changes what fills it: scheduled_time to publish on another date, topic_id to swap the idea, title to reword the headline the calendar shows. There is no separate reschedule call — moving a slot is writing its time.
Any edit here hands the slot to you permanently: the desk stops planning it and will not change it again. Swapping the topic returns the previous one to the backlog and takes the new one out of it.
path Parameters
website_idId of the parent website.
editorial_slot_idId of the parent editorial_slot.
query Parameters
update_maskComma-separated field paths to merge. A field named here and sent as null is cleared; without the mask a null is dropped (§7, §11).
Headers
If-MatchThe etag the client last read. A mismatch is ABORTED (409) with the current resource in the error details (§14).
Update editorial_slot › Request Body
scheduled_timeWhen this piece goes out. Unique across the website — one slot per moment — and the order the calendar is read in. Moving a slot is a write of this field, and it takes the slot out of the desk's hands.
topic_idThe editorial_topics resource filling this slot. Empty on a slot someone put on the calendar with a title and no backlog entry.
titleThe headline this slot stands for, copied from its topic when the slot was made. It is a snapshot, so a month of calendar draws without reading every topic — and so a topic renamed later does not rewrite a slot that already produced a draft.
content_modeWho fills this one slot, overriding the plan's content_mode for this date alone — "I am writing this Friday myself". Absent, the plan decides. It can be set while the slot is still PLANNED or FAILED, not once its draft exists.
Update editorial_slot › Responses
The updated resource.
nameThe resource name (§5) — the identity of this resource, and the path that addresses it: websites/{website}/cms_pages/{cms_page}. It is the handle to store, not a human label.
idThe last segment of name on its own, for a client that needs to build a child URL. Unique inside its parent, never across the platform.
create_timeWhen the resource was created (RFC 3339, UTC).
update_timeWhen the resource last changed (RFC 3339, UTC).
etagVersion of the persisted state. Send it back in If-Match on Update or Delete and the write is rejected with ABORTED if anyone else changed the resource meanwhile (§14).
scheduled_timeWhen this piece goes out. Unique across the website — one slot per moment — and the order the calendar is read in. Moving a slot is a write of this field, and it takes the slot out of the desk's hands.
topic_idThe editorial_topics resource filling this slot. Empty on a slot someone put on the calendar with a title and no backlog entry.
titleThe headline this slot stands for, copied from its topic when the slot was made. It is a snapshot, so a month of calendar draws without reading every topic — and so a topic renamed later does not rewrite a slot that already produced a draft.
target_typeWhat this slot produces. Defaults to the plan's and cannot be changed afterwards: a slot that switched kind mid-flight would leave its draft behind with nothing pointing at it.
target_idThe blog_posts resource this slot created. It is also what makes preparing a draft safe to repeat — a slot that already names its post never gets a second one.
statusWhere the slot stands: PLANNED before its draft exists, GENERATING while a producer is writing it, DRAFTED once it does, PUBLISHED once that post is live, SKIPPED if the date was dropped, FAILED if preparing the draft did not work. FAILED is retried where the retry is free, and left to you where it is not.
originAUTO while the slot is the desk's to manage, MANUAL once a person created or edited it — after which the desk leaves it alone for good. This is the whole of "a person outranks the schedule".
last_errorWhy the last attempt to prepare this slot's draft did not work. Cleared as soon as one succeeds, so it always describes the present.
content_modeWho fills this one slot, overriding the plan's content_mode for this date alone — "I am writing this Friday myself". Absent, the plan decides. It can be set while the slot is still PLANNED or FAILED, not once its draft exists.
generation_idThe latest editorial_generations run producing this slot's content, when a producer other than a person is writing it. Absent on a slot nobody generated.
review_verdictWhat the producer's own check made of the content: PASSED, or NEEDS_REVIEW when a person should read it before it goes out. A snapshot of the run's verdict, kept here so a month of calendar draws its badges without reading every run.
Materialize (editorial_slots)
Prepares this slot's draft now, rather than waiting until its date comes near. The draft is created switched off, dated at the slot's moment, with the topic's note as its teaser and the categories, tags and byline the topic or the plan calls for — so whoever writes it opens a post that already knows what it is for.
Safe to repeat: a slot that already has content answers with the same content instead of making a second copy. It never publishes anything — that is :publish.
path Parameters
website_idId of the parent website.
editorial_slot_idId of the parent editorial_slot.
Materialize (editorial_slots) › Request Body optional
Materialize (editorial_slots) › Responses
The affected resource, or the method’s own response object (§10).
Publish (editorial_slots)
Makes this slot's draft live. The date was already set when the draft was prepared, so this only flips it on; the slot reaches its published state and its topic is marked used.
Nothing publishes on its own — an article the platform wrote nothing into going out unread is a defect, not a feature — so this call is the only way a planned piece becomes visible.
path Parameters
website_idId of the parent website.
editorial_slot_idId of the parent editorial_slot.
Publish (editorial_slots) › Request Body optional
Publish (editorial_slots) › Responses
The affected resource, or the method’s own response object (§10).
Skip (editorial_slots)
Drops this date without giving it up: the slot stays on the calendar as skipped, its topic returns to the backlog, and — because the moment is still taken — the desk will not quietly plan something else there. That is the difference from Delete, and it is how «not this week» survives the next time the calendar is filled.
A slot whose post is already published cannot be skipped.
path Parameters
website_idId of the parent website.
editorial_slot_idId of the parent editorial_slot.
Skip (editorial_slots) › Request Body optional
Skip (editorial_slots) › Responses
The affected resource, or the method’s own response object (§10).
List editorial_topics
One item of the backlog: something this website intends to write about. A topic outlives the article it becomes — it records which slot consumed it, and one that was turned down stays turned down instead of resurfacing the next time the calendar is filled. :batch_create adds a whole list in one call, :reject and :restore move it in and out of the backlog, and :accept takes in an idea the desk's AI proposed.
path Parameters
website_idId of the parent website.
query Parameters
page_sizeRows per page. Over the maximum is clamped, not rejected.
page_tokenOpaque token from a previous next_page_token. A token minted under a different order_by/filter is rejected.
skipRows to skip before the page (AIP-158). skip + page_size is capped at 10000; beyond that is OUT_OF_RANGE.
order_byComma-separated field [asc|desc], at most 3 keys. Default: create_time desc. Sortable: create_time, priority, title.
filterAIP-160 subset (§8). Filterable: author_id, category_ids, create_time, keywords, origin, priority, slot_id, status, tag_ids, title. A field outside the list is INVALID_ARGUMENT.
List editorial_topics › Responses
One page of editorial_topics.
This page of editorial_topics, in the requested order.
next_page_tokenOpaque. Absent or empty means this was the last page.
total_sizeRows in the whole filtered collection, not in this page.
Create editorial_topic
One item of the backlog: something this website intends to write about. A topic outlives the article it becomes — it records which slot consumed it, and one that was turned down stays turned down instead of resurfacing the next time the calendar is filled. :batch_create adds a whole list in one call, :reject and :restore move it in and out of the backlog, and :accept takes in an idea the desk's AI proposed.
path Parameters
website_idId of the parent website.
Create editorial_topic › Request Body
titleWhat the article is about, in a line. It becomes the headline of the draft the topic turns into, and the label the calendar shows for its slot.
briefThe editor's note on what the article should say. It is copied into the draft's teaser, so whoever writes the post opens it and finds the assignment already there.
keywordsThe search terms this article is meant to answer — a note to the writer, not something the platform acts on.
category_idsThe blog_categories this topic's draft is filed under. Set, it replaces the plan's defaults outright rather than adding to them.
tag_idsThe blog_tags this topic's draft carries, with the same rule as category_ids: set, it replaces the plan's defaults.
author_idThe blog_authors resource this topic's draft is credited to, instead of the plan's default.
priorityWhich topic is taken next: higher goes first, and equals are taken oldest first. Sort by it inside a status filter — that is the pair an index backs.
Create editorial_topic › Responses
The created resource.
nameThe resource name (§5) — the identity of this resource, and the path that addresses it: websites/{website}/cms_pages/{cms_page}. It is the handle to store, not a human label.
idThe last segment of name on its own, for a client that needs to build a child URL. Unique inside its parent, never across the platform.
create_timeWhen the resource was created (RFC 3339, UTC).
update_timeWhen the resource last changed (RFC 3339, UTC).
etagVersion of the persisted state. Send it back in If-Match on Update or Delete and the write is rejected with ABORTED if anyone else changed the resource meanwhile (§14).
titleWhat the article is about, in a line. It becomes the headline of the draft the topic turns into, and the label the calendar shows for its slot.
briefThe editor's note on what the article should say. It is copied into the draft's teaser, so whoever writes the post opens it and finds the assignment already there.
keywordsThe search terms this article is meant to answer — a note to the writer, not something the platform acts on.
category_idsThe blog_categories this topic's draft is filed under. Set, it replaces the plan's defaults outright rather than adding to them.
tag_idsThe blog_tags this topic's draft carries, with the same rule as category_ids: set, it replaces the plan's defaults.
author_idThe blog_authors resource this topic's draft is credited to, instead of the plan's default.
priorityWhich topic is taken next: higher goes first, and equals are taken oldest first. Sort by it inside a status filter — that is the pair an index backs.
statusWhere the topic stands: PROPOSED while an idea the desk's AI suggested waits for a person, CANDIDATE while it waits in the backlog, PLANNED once a slot holds it, USED once that slot's post is live, REJECTED if it was turned down. Moved by :accept, :reject, :restore and by the desk itself, never by writing this field.
slot_idThe editorial_slots resource holding this topic while it is PLANNED or USED. Empty while it is still in the backlog.
originWho put the topic on the list: MANUAL for one a person entered, SUGGESTED for one a TOPICS run of editorial_generations proposed.
generation_idThe editorial_generations run that proposed this topic. Absent on a topic a person entered. Which topics a run proposed is that run's own result.
Get editorial_topic
One item of the backlog: something this website intends to write about. A topic outlives the article it becomes — it records which slot consumed it, and one that was turned down stays turned down instead of resurfacing the next time the calendar is filled. :batch_create adds a whole list in one call, :reject and :restore move it in and out of the backlog, and :accept takes in an idea the desk's AI proposed.
path Parameters
website_idId of the parent website.
editorial_topic_idId of the parent editorial_topic.
Headers
If-None-MatchA matching etag answers 304 with no body (§16).
Get editorial_topic › Responses
The resource.
nameThe resource name (§5) — the identity of this resource, and the path that addresses it: websites/{website}/cms_pages/{cms_page}. It is the handle to store, not a human label.
idThe last segment of name on its own, for a client that needs to build a child URL. Unique inside its parent, never across the platform.
create_timeWhen the resource was created (RFC 3339, UTC).
update_timeWhen the resource last changed (RFC 3339, UTC).
etagVersion of the persisted state. Send it back in If-Match on Update or Delete and the write is rejected with ABORTED if anyone else changed the resource meanwhile (§14).
titleWhat the article is about, in a line. It becomes the headline of the draft the topic turns into, and the label the calendar shows for its slot.
briefThe editor's note on what the article should say. It is copied into the draft's teaser, so whoever writes the post opens it and finds the assignment already there.
keywordsThe search terms this article is meant to answer — a note to the writer, not something the platform acts on.
category_idsThe blog_categories this topic's draft is filed under. Set, it replaces the plan's defaults outright rather than adding to them.
tag_idsThe blog_tags this topic's draft carries, with the same rule as category_ids: set, it replaces the plan's defaults.
author_idThe blog_authors resource this topic's draft is credited to, instead of the plan's default.
priorityWhich topic is taken next: higher goes first, and equals are taken oldest first. Sort by it inside a status filter — that is the pair an index backs.
statusWhere the topic stands: PROPOSED while an idea the desk's AI suggested waits for a person, CANDIDATE while it waits in the backlog, PLANNED once a slot holds it, USED once that slot's post is live, REJECTED if it was turned down. Moved by :accept, :reject, :restore and by the desk itself, never by writing this field.
slot_idThe editorial_slots resource holding this topic while it is PLANNED or USED. Empty while it is still in the backlog.
originWho put the topic on the list: MANUAL for one a person entered, SUGGESTED for one a TOPICS run of editorial_generations proposed.
generation_idThe editorial_generations run that proposed this topic. Absent on a topic a person entered. Which topics a run proposed is that run's own result.
Delete editorial_topic
Removes a topic from the backlog for good. A topic a calendar slot is holding cannot be deleted — skip that slot first, which returns the topic to the backlog. Nothing cascades in either direction: deleting a topic never removes a slot, and deleting a slot never removes a topic. To take an idea off the list while keeping the record of it, use :reject.
path Parameters
website_idId of the parent website.
editorial_topic_idId of the parent editorial_topic.
Headers
If-MatchThe etag the client last read. A mismatch is ABORTED (409) with the current resource in the error details (§14).
Delete editorial_topic › Responses
Deleted. No body (§7).
Update editorial_topic
One item of the backlog: something this website intends to write about. A topic outlives the article it becomes — it records which slot consumed it, and one that was turned down stays turned down instead of resurfacing the next time the calendar is filled. :batch_create adds a whole list in one call, :reject and :restore move it in and out of the backlog, and :accept takes in an idea the desk's AI proposed.
path Parameters
website_idId of the parent website.
editorial_topic_idId of the parent editorial_topic.
query Parameters
update_maskComma-separated field paths to merge. A field named here and sent as null is cleared; without the mask a null is dropped (§7, §11).
Headers
If-MatchThe etag the client last read. A mismatch is ABORTED (409) with the current resource in the error details (§14).
Update editorial_topic › Request Body
titleWhat the article is about, in a line. It becomes the headline of the draft the topic turns into, and the label the calendar shows for its slot.
briefThe editor's note on what the article should say. It is copied into the draft's teaser, so whoever writes the post opens it and finds the assignment already there.
keywordsThe search terms this article is meant to answer — a note to the writer, not something the platform acts on.
category_idsThe blog_categories this topic's draft is filed under. Set, it replaces the plan's defaults outright rather than adding to them.
tag_idsThe blog_tags this topic's draft carries, with the same rule as category_ids: set, it replaces the plan's defaults.
author_idThe blog_authors resource this topic's draft is credited to, instead of the plan's default.
priorityWhich topic is taken next: higher goes first, and equals are taken oldest first. Sort by it inside a status filter — that is the pair an index backs.
Update editorial_topic › Responses
The updated resource.
nameThe resource name (§5) — the identity of this resource, and the path that addresses it: websites/{website}/cms_pages/{cms_page}. It is the handle to store, not a human label.
idThe last segment of name on its own, for a client that needs to build a child URL. Unique inside its parent, never across the platform.
create_timeWhen the resource was created (RFC 3339, UTC).
update_timeWhen the resource last changed (RFC 3339, UTC).
etagVersion of the persisted state. Send it back in If-Match on Update or Delete and the write is rejected with ABORTED if anyone else changed the resource meanwhile (§14).
titleWhat the article is about, in a line. It becomes the headline of the draft the topic turns into, and the label the calendar shows for its slot.
briefThe editor's note on what the article should say. It is copied into the draft's teaser, so whoever writes the post opens it and finds the assignment already there.
keywordsThe search terms this article is meant to answer — a note to the writer, not something the platform acts on.
category_idsThe blog_categories this topic's draft is filed under. Set, it replaces the plan's defaults outright rather than adding to them.
tag_idsThe blog_tags this topic's draft carries, with the same rule as category_ids: set, it replaces the plan's defaults.
author_idThe blog_authors resource this topic's draft is credited to, instead of the plan's default.
priorityWhich topic is taken next: higher goes first, and equals are taken oldest first. Sort by it inside a status filter — that is the pair an index backs.
statusWhere the topic stands: PROPOSED while an idea the desk's AI suggested waits for a person, CANDIDATE while it waits in the backlog, PLANNED once a slot holds it, USED once that slot's post is live, REJECTED if it was turned down. Moved by :accept, :reject, :restore and by the desk itself, never by writing this field.
slot_idThe editorial_slots resource holding this topic while it is PLANNED or USED. Empty while it is still in the backlog.
originWho put the topic on the list: MANUAL for one a person entered, SUGGESTED for one a TOPICS run of editorial_generations proposed.
generation_idThe editorial_generations run that proposed this topic. Absent on a topic a person entered. Which topics a run proposed is that run's own result.
Accept (editorial_topics)
Takes a topic the desk's AI proposed into the backlog, where the calendar can plan it. A proposed topic sits outside the calendar until somebody accepts it — that is the whole point of the approval step — and :reject is the other answer. Accepting a topic that is already a candidate is not an error; anything else answers FAILED_PRECONDITION.
path Parameters
website_idId of the parent website.
editorial_topic_idId of the parent editorial_topic.
Accept (editorial_topics) › Request Body optional
Accept (editorial_topics) › Responses
The affected resource, or the method’s own response object (§10).
Reject (editorial_topics)
Turns a topic down: it stays on record but stops being offered when the calendar is filled. This is the point of keeping the backlog separate from the articles — a rejected idea does not resurface next month because nobody remembered rejecting it.
Only a topic still waiting in the backlog can be rejected; if a slot is already holding it, skip that slot first. Rejecting an already rejected topic is not an error.
path Parameters
website_idId of the parent website.
editorial_topic_idId of the parent editorial_topic.
Reject (editorial_topics) › Request Body optional
Reject (editorial_topics) › Responses
The affected resource, or the method’s own response object (§10).
Restore (editorial_topics)
Puts a rejected topic back in the backlog, where the calendar can pick it up again. The counterpart of :reject, and only valid on a topic that was rejected.
path Parameters
website_idId of the parent website.
editorial_topic_idId of the parent editorial_topic.
Restore (editorial_topics) › Request Body optional
Restore (editorial_topics) › Responses
The affected resource, or the method’s own response object (§10).
Batch create (editorial_topics)
Adds a whole list of topics in one call — the shape a «one idea per line» box in an editor should send instead of a burst of single Creates. Send them under editorial_topics, exactly as each would be sent on its own.
Atomic: if any entry is rejected, nothing is written. Every topic arrives in the backlog as a candidate, in the order given.
path Parameters
website_idId of the parent website.
Batch create (editorial_topics) › Request Body optional
Batch create (editorial_topics) › Responses
The affected resource, or the method’s own response object (§10).