Newsroom tools

Everything so far makes one video on request. A newsroom is the other half: a standing configuration that finds stories and publishes them on a schedule, without anybody asking each time.

What a newsroom is made of

A newsroom holds the brand: its name, its website, its logo and colours, and which saved style each video should use. It holds the list of sites its stories come from. And it holds one or more series.

The series is what actually runs. The scheduler iterates series, not newsrooms: each one owns its own times of day, the rules deciding which of the newsroom’s articles belong to it, the direction its scripts are written under, and where its videos are published. Every newsroom is created with one called General; a second series is how you run, say, a daily explainer alongside a weekly quiz off the same pool of articles.

Nothing publishes until both switches are on (the newsroom’s update_newsroom_settings and the series’ update_series), and a newsroom with no data source has nothing to publish even then.

Setting one up

The sequence, end to end:

create_newsroom                 → the shell, paused, with a General series
create_brand_kit_from_website   → reads the publisher's site for colours,
                                  fonts and logo, and points the newsroom at it
add_data_source                 → one call per site to pull articles from
update_series                   → times of day, timezone, channels
update_newsroom_settings        → active: true, once the user says so

Two of these reach the open web, and are slow

add_data_source runs a five-tier discovery pipeline against the URL you give it (RSS, then sitemap, then a repeated-DOM pattern, then generated extraction code), and create_brand_kit_from_website scrapes and analyses the site’s homepage. Each can take up to a minute or two. Tell the user before you start one, and never fire several in parallel hoping one lands.

Never switch a newsroom on unasked

active: true means it starts publishing to real channels, on a schedule, under the user’s name. Build the whole thing, show what it will do, and ask. The same goes for run_newsroom_now, which produces a real video and spends the account’s credits.

Reading before writing

There is no ambient selection over MCP. Every tool here takes a newsroom argument (an id, or the exact name), and there is no “the one they have open” to fall back on. Start with list_newsrooms, then get_newsroom for the detail.

list_newsrooms

List the user's newsrooms: id, name, whether automation is running, which organization it is shared with, and how many series and sources each has. Start here when the user names a newsroom you have not resolved yet.

Takes no parameters.

Returns

Field	Type	Description
card always	"newsroom_list"	What kind of result this is.
newsrooms always	object[]	Every newsroom the user owns or a teammate has shared with them.

get_newsroom

Read one newsroom in full: its name and website, the master on/off switch, the source mode, every data source, every series with its schedule and channels, and the six style pointers resolved to names. Read this before changing anything you are not certain about.

Parameter	Type	Description
newsroom	string	Which newsroom: its id, or its exact name. Omit to use the one the user currently has open.

Returns: The whole setup: the newsroom, its series and its data sources.

Field	Type	Description
card always	"newsroom"	What kind of result this is.
newsroom always	object	The newsroom itself: the brand, the master switch and the style pointers.
series always	object[]	Its series. A newsroom with none publishes nothing.
data_sources always	object[]	The sites it pulls stories from. Empty means it has nothing to publish.

A name that misses tells you the names that hit

Pass a newsroom, series, style or source that does not exist and the error carries the list of ones that do. Offer those rather than guessing again, and if two rows share a name, the call refuses rather than picking, so pass the id.

The newsroom itself

create_newsroom

Create a new newsroom. It starts PAUSED with one series called General and no data sources. Pass website to record the publisher's homepage (used as the RSS channel link). It does NOT add a data source or build a brand kit, which are the separate calls you should make next. This replaces the guided setup wizard, so you are responsible for finishing the job: brand, sources, schedule.

Parameter	Type	Description
name required	string	What to call it, e.g. "Yahoo News".
website	string	The publisher's homepage, https only. Optional.
organization	string	Share it with an organization: its id or exact name. Omit to keep it personal.

Returns

Field	Type	Description
card always	"newsroom"	What kind of result this is.
newsroom always	object	The newsroom that was created. It starts paused, with no sources.
created	boolean	Always true here; this tool only creates.
series	object[]	The General series every newsroom is created with.
next_step	string	Guidance for you, not for the user. Act on it; do not read it out.
select	object	What the web app should switch the user to: the row this call just created. In-app only; ignore it.
refresh	string[]	Which parts of the dashboard this change made stale. In-app only; ignore it.

update_newsroom

Change a newsroom's own settings: its name, its website, which organization it is shared with, its six style pointers (script style, speaker style, voiceover, video format, brand kit, captions), its pinned layout template, whether automated videos use the article's lead photo, which aspect ratios its videos render in, whether performance auto-optimisation is on, and the narration voice rotation. These are the NEWSROOM rung; a series that sets its own value still wins.

Parameter	Type	Description
newsroom	string	Which newsroom: its id, or its exact name. Omit to use the one the user currently has open.
name	string
website	string	https URL, or "none" to clear.
organization	string	Organization id or name to share with, or "none" to make it personal.
script_style	string	Script style template: id or name. "none" clears it.
speaker_style	string	Speaker style: id or name. "none" clears it.
voiceover	string	Voiceover/TTS template: id or name. "none" clears it.
video_format	string	Video format template: id or name. "none" clears it.
brand_kit	string	Brand kit: id or name. "none" clears it.
captions	string	Caption preset: id or name. "none" clears it.
layout_template	string	Fixed layout for AI-NARRATED scheduled videos: a builtin slug (e.g. narrated) or a custom template id. "none" clears it. Only layouts with nobody on camera and an AI voice fit here.
speaker_layout_template	string	Fixed layout for scheduled videos a PERSON RECORDS (speaker run times): a builtin slug (e.g. split_screen, full_frame, cut_in, roto_speaker) or a custom template id. "none" clears it. Only layouts with someone on camera and recorded audio fit here.
use_article_hero_image	boolean	Use the scraped article's lead photo as b-roll in automated videos.
caption_emphasis	boolean	Emphasis moments: a few caption lines per video set in an accent face (a year huge, a quote on a paper slip, "not X, Y"). Every other line stays in the newsroom's caption style. On by default.
video_look	string	The film/print look over the footage, under the captions. "auto" (default) picks one per video from its pictures: print for old ads, archival for old footage, light_film otherwise. "none" draws nothing. One of: auto, none, light_film, print, archival.
aspect_ratios	any	Which shapes this newsroom's videos render in, PRIMARY FIRST, any of 9:16, 16:9, 1:1. Each extra shape is a separate render. The first one is what downloads, thumbnails and Instagram publishing use. Pass "inherit" to fall back to the video format template's own setting.
auto_optimize	boolean	Let measured post performance steer the next video's settings. Off by default.
voice_rotation	object[]	Ordered narration voices so consecutive videos don't share a narrator. Each entry needs voiceId and voiceName (get them from list_voices). An empty array turns rotation off.

Returns

Field	Type	Description
card always	"settings"	What kind of result this is.
applied always	object | null	The settings that actually landed, keyed by field, with ids resolved to names. Summarise from THIS, not from what was requested. A field missing here did not change.
scope	string	Which rung was written: newsroom, newsroom_settings or series.
newsroom	object | null	The row this result is about.
series	object | null	The row this result is about.
deleted	boolean	Present and true when the row was archived.
refresh	string[]	Which parts of the dashboard this change made stale. In-app only; ignore it.

Style resolves down a chain

A video’s brand kit, captions, voiceover, script style, speaker style, video format and layout each resolve down three rungs:

the series' own choice  →  the newsroom's  →  the account default

update_newsroom writes the middle rung and update_series writes the top one. That is why setting a brand kit on the newsroom can appear to do nothing: a series with its own pointer still wins. get_newsroom shows you both, and setting a series’ style to "none" clears the override so it inherits again.

Style arguments take a name or an id ("brand_kit": "Yahoo News" is fine), and the result’s applied object reports the name that was actually resolved, so you can tell the user what landed rather than what you asked for.

update_newsroom_settings

Turn a newsroom's publishing on or off, turn its story collection on or off, and set where its stories come from: the source mode (urls, news-api, scripts, themes), the News API key, and the News API category filter. Publishing and collection are SEPARATE switches; see each one's description.

Parameter	Type	Description
newsroom	string	Which newsroom: its id, or its exact name. Omit to use the one the user currently has open.
active	boolean	Publishing. False pauses every series in the newsroom, so nothing is posted on the schedule. It does NOT stop the newsroom collecting stories; use ingest_active for that.
ingest_active	boolean	Collecting stories. True keeps reading the newsroom's sources hourly so its article list stays current, whether or not it is publishing. Turning this off freezes the "From your source" picker at whatever it last saw.
data_source	string	Where stories come from. "urls" is the RSS/URL discovery path. One of: news-api, urls, scripts, themes.
news_api_key	string	NewsAPI key, only for data_source news-api. Write-only: it is never read back.
news_categories	string[]	News API category filter. An empty array clears it.

Returns

Field	Type	Description
card always	"settings"	What kind of result this is.
applied always	object | null	The settings that actually landed, keyed by field, with ids resolved to names. Summarise from THIS, not from what was requested. A field missing here did not change.
scope	string	Which rung was written: newsroom, newsroom_settings or series.
newsroom	object | null	The row this result is about.
series	object | null	The row this result is about.
deleted	boolean	Present and true when the row was archived.
refresh	string[]	Which parts of the dashboard this change made stale. In-app only; ignore it.

delete_newsroom

Archive a newsroom. Its run history is preserved. Blocked when it is the user's last one. Owner only: an org admin cannot delete someone else's newsroom. Confirm with the user before calling.

Parameter	Type	Description
newsroom	string	Which newsroom: its id, or its exact name. Omit to use the one the user currently has open.

Returns

Field	Type	Description
card always	"settings"	What kind of result this is.
applied always	object | null	The settings that actually landed, keyed by field, with ids resolved to names. Summarise from THIS, not from what was requested. A field missing here did not change.
scope	string	Which rung was written: newsroom, newsroom_settings or series.
newsroom	object | null	The row this result is about.
series	object | null	The row this result is about.
deleted	boolean	Present and true when the row was archived.
refresh	string[]	Which parts of the dashboard this change made stale. In-app only; ignore it.

Series

list_series

List a newsroom's series with their schedules, channels, filters and last run. The series is the schedulable unit: the scheduler iterates these, not newsrooms.

Parameter	Type	Description
newsroom	string	Which newsroom: its id, or its exact name. Omit to use the one the user currently has open.

Returns

Field	Type	Description
card always	"series_list"	What kind of result this is.
series always	object[]	Every live series in the newsroom, in the order they are shown.
newsroom	object | null	The row this result is about.

create_series

Add a content series to a newsroom: a distinct strand with its own schedule, filters and style (e.g. a Quizzes series beside a News one). It starts PAUSED and unfiltered, seeded from the newsroom's existing default series. Say what belongs in it with classification_prompt.

Parameter	Type	Description
name required	string
newsroom	string	Which newsroom: its id, or its exact name. Omit to use the one the user currently has open.
classification_prompt	string	Plain-English description of what belongs in this series, handed to the classifier verbatim.
classification_mode	string	Defaults to hybrid. One of: rules, hybrid, llm, off.

Returns

Field	Type	Description
card always	"series"	What kind of result this is.
series always	object	One content series, the schedulable unit. The scheduler iterates these, not newsrooms.
created	boolean	Always true here; this tool only creates.
newsroom	object | null	The row this result is about.
next_step	string	Guidance for you, not for the user. Act on it; do not read it out.
select	object	What the web app should switch the user to: the row this call just created. In-app only; ignore it.
refresh	string[]	Which parts of the dashboard this change made stale. In-app only; ignore it.

update_series

Change anything about one series: name, on/off, schedule (frequency, times of day, timezone), which articles it takes (classification prompt/mode and keyword filters) or a knowledge base to make evergreen videos from instead, the script direction it writes under, where it publishes (Instagram, email), and its own style pointers, which override the newsroom's. Set a style to "none" to fall back to the newsroom.

Parameter	Type	Description
newsroom	string	Which newsroom: its id, or its exact name. Omit to use the one the user currently has open.
series	string	Which series: its id, or its exact name. Omit to use the series the user has open (or the only one, if there is one).
name	string
active	boolean	Run this series on its schedule.
frequency	string	One of: daily, weekly, on-arrival, manual.
run_times	string[]	Times of day as "HH:MM" 24-hour, up to 12. Each one produces one post.
timezone	string	IANA name, e.g. America/New_York.
custom_instructions	string	Freeform direction injected verbatim into the script generator for every video this series makes. "none" clears it.
classification_prompt	string	Plain-English description of what belongs in this series. "none" clears it.
classification_mode	string	One of: rules, hybrid, llm, off.
source_filter	object	Keyword/URL rules over the newsroom's shared pool: match_fields, include_keywords, exclude_keywords, url_patterns, hosts, require_categories, exclude_categories, authors, title_patterns, exclude_title_patterns. Excludes always win; an empty filter matches everything.
channels	object	Distribution toggles: { instagram, "email-self", "email-blast" } as booleans.
email_recipients	string
email_note	string
instagram_account	string	Connected Instagram account id, or "none" to disconnect.
knowledge_base	string	Where this series' scheduled videos get their story: a knowledge base of this newsroom (its id or exact name) makes evergreen videos from it, one angle per video. "none" points it back at the newsroom's own stories.
style_preset	string	One of: house, shorts, explainer, custom.
script_style	string	Script style template: id or name. "none" clears it.
speaker_style	string	Speaker style: id or name. "none" clears it.
voiceover	string	Voiceover/TTS template: id or name. "none" clears it.
video_format	string	Video format template: id or name. "none" clears it.
brand_kit	string	Brand kit: id or name. "none" clears it.
captions	string	Caption preset: id or name. "none" clears it.
layout_template	string	Fixed layout for AI-NARRATED scheduled videos: a builtin slug (e.g. narrated) or a custom template id. "none" clears it. Only layouts with nobody on camera and an AI voice fit here.
speaker_layout_template	string	Fixed layout for scheduled videos a PERSON RECORDS (speaker run times): a builtin slug (e.g. split_screen, full_frame, cut_in, roto_speaker) or a custom template id. "none" clears it. Only layouts with someone on camera and recorded audio fit here.
use_article_hero_image	string	"true", "false", or "inherit" to fall back to the newsroom's answer.
caption_emphasis	string	Emphasis moments for THIS series: "true", "false", or "inherit" to use the newsroom's.
video_look	string	The look for THIS series: one of auto, none, light_film, print, archival, or "inherit" to use the newsroom's.
aspect_ratios	any	Which shapes THIS SERIES' videos render in, primary first, any of 9:16, 16:9, 1:1. "inherit" falls back to the newsroom's answer.
auto_optimize	string	"true", "false", or "inherit" to fall back to the newsroom's answer.
voice_rotation	object[]	Ordered narration voices for this series. Entries need voiceId and voiceName. Empty array turns it off and falls back to the newsroom's.

Returns

Field	Type	Description
card always	"series"	What kind of result this is.
series always	object	One content series, the schedulable unit. The scheduler iterates these, not newsrooms.
newsroom	object | null	The row this result is about.
applied	object | null	The settings that actually landed, keyed by field, with ids resolved to names. Summarise from THIS, not from what was requested. A field missing here did not change.
refresh	string[]	Which parts of the dashboard this change made stale. In-app only; ignore it.

Which articles a series takes

Two mechanisms, and they answer different questions:

• classification_prompt is a plain-English description of what belongs in the series, handed to a classifier. It is the one a user can write well.
• source_filter is keyword and URL rules over the same pool. Excludes are absolute; includes are a shortcut. An empty filter matches everything.

classification_mode picks between them: rules uses only the filter, llm only the prompt, hybrid (the default) runs the filter first and the classifier over what is left, and off disables both.

Three-state settings

use_article_hero_image and auto_optimize on a series take "true", "false" or "inherit". They are genuinely three values: "false" means this series opts out, "inherit" means it follows the newsroom. On the newsroom itself only true and false exist; that rung is the bottom of the chain and always has an answer.

aspect_ratios is three-state on both rungs, which is the exception worth knowing. It takes a list drawn from 9:16, 16:9 and 1:1 (a bare string is accepted for one), or the literal "inherit", and "inherit" is meaningful on a newsroom too, because the rung below it is the video format template’s own setting rather than a fixed default.

The order is the answer, not a detail. The first ratio is the primary: it is the file long_form_url points at, the one the thumbnail is cut from, and the one Instagram publishing posts. Every extra ratio is a separate render, so ["9:16", "16:9"] costs twice what ["9:16"] does.

A layout template overrides all of this. Its spec.aspectRatio is a single shape and it replaces the list outright: one template is one shape.

delete_series

Archive a series. Blocked when it is the newsroom's last one. Confirm with the user before calling.

Parameter	Type	Description
series required	string	Which series: its id, or its exact name. Omit to use the series the user has open (or the only one, if there is one).
newsroom	string	Which newsroom: its id, or its exact name. Omit to use the one the user currently has open.

Returns

Field	Type	Description
card always	"series"	What kind of result this is.
series always	object	The series that was archived. Its run history is kept.
deleted	boolean	Always true here; the series was archived.
newsroom	object | null	The row this result is about.
applied	object | null	The settings that actually landed, keyed by field, with ids resolved to names. Summarise from THIS, not from what was requested. A field missing here did not change.
refresh	string[]	Which parts of the dashboard this change made stale. In-app only; ignore it.

Where the stories come from

list_data_sources

List the URLs a newsroom pulls stories from, with the extraction strategy each one locked in and its current health.

Parameter	Type	Description
newsroom	string	Which newsroom: its id, or its exact name. Omit to use the one the user currently has open.

Returns

Field	Type	Description
card always	"sources"	What kind of result this is.
data_sources always	object[]	Every site this newsroom pulls from, active or paused.
newsroom	object | null	The row this result is about.

add_data_source

Point a newsroom at a website. Runs the discovery pipeline (RSS, then sitemap, then a repeated-DOM pattern, then generated code), locks in the cheapest strategy that works, and saves it. This takes up to a couple of minutes and reaches a third-party site. A section or category page works better than a homepage. Always read the sample_titles it returns: they are what this newsroom will make videos about, and a strategy that locked in on the wrong part of a site (a weather directory, a tag index) still reports success. When they are not headlines, call this again with the same URL and that strategy in `avoid`.

Parameter	Type	Description
url required	string	The page to pull articles from, http(s).
newsroom	string	Which newsroom: its id, or its exact name. Omit to use the one the user currently has open.
label	string	A short name for it. Optional.
avoid	string[]	Extraction strategies to skip this time, because a previous run of this URL locked one in on the wrong pages. Pass every strategy already rejected, not just the last.

Returns

Field	Type	Description
card always	"source"	What kind of result this is.
data_source always	object	One website this newsroom pulls stories from.
newsroom	object | null	The row this result is about.
strategy	string	Which tier of the discovery pipeline won. rss is the cheapest, browser_llm the most expensive.
sample_titles	string[]	A few headlines discovery found, so the user can check it read the right page.
refresh	string[]	Which parts of the dashboard this change made stale. In-app only; ignore it.

A section or category page works far better than a homepage. The pipeline is looking for a list of articles, and a homepage is usually a collage. When discovery fails, the error names the tiers it tried; suggest a better URL rather than retrying the same one.

update_data_source

Pause, resume or rename one of a newsroom's data sources.

Parameter	Type	Description
source required	string	The source's id or its URL.
newsroom	string	Which newsroom: its id, or its exact name. Omit to use the one the user currently has open.
active	boolean
label	string

Returns

Field	Type	Description
card always	"source"	What kind of result this is.
data_source always	object	One website this newsroom pulls stories from.
newsroom	object | null	The row this result is about.
applied	object | null	The settings that actually landed, keyed by field, with ids resolved to names. Summarise from THIS, not from what was requested. A field missing here did not change.
refresh	string[]	Which parts of the dashboard this change made stale. In-app only; ignore it.

remove_data_source

Remove a data source from a newsroom for good. Pausing it with update_data_source is usually what the user wants instead. Confirm before calling.

Parameter	Type	Description
source required	string	The source's id or its URL.
newsroom	string	Which newsroom: its id, or its exact name. Omit to use the one the user currently has open.

Returns

Field	Type	Description
card always	"source"	What kind of result this is.
data_source always	object	The source that was removed.
deleted	boolean	Always true here; the source was removed for good.
newsroom	object | null	The row this result is about.
applied	object | null	The settings that actually landed, keyed by field, with ids resolved to names. Summarise from THIS, not from what was requested. A field missing here did not change.
refresh	string[]	Which parts of the dashboard this change made stale. In-app only; ignore it.

Brand and style

list_style_library

List the style rows a newsroom can be pointed at: brand kits, caption presets, voiceover templates, script styles, speaker styles, video formats, or layout templates. Use it before naming one, so you offer options that exist.

Parameter	Type	Description
kind required	string	One of: script_style, speaker_style, voiceover, video_format, brand_kit, captions, layout_templates.
newsroom	string	Which newsroom: its id, or its exact name. Omit to use the one the user currently has open.

Returns

Field	Type	Description
card always	"style_library"	What kind of result this is.
kind always	string	Which library this is: brand_kit, captions, voiceover, script_style, speaker_style, video_format or layout_templates.
items always	object[]	The rows the user can point a newsroom or series at.
builtin	string[]	Layout slugs that ship with the product and have no row.
note	string	Guidance for you, not for the user. Act on it; do not read it out.

create_brand_kit_from_website

Read a publisher's website and build a brand kit from it (colours, fonts and logo), then optionally point a newsroom (or one series) at it. This reaches a third-party site and takes up to a minute. It never changes the user's account-wide default.

Parameter	Type	Description
website required	string	The site to read, e.g. https://www.yahoo.com
name	string	What to call the kit. Defaults to the brand name found on the site.
newsroom	string	Which newsroom: its id, or its exact name. Omit to use the one the user currently has open.
apply_to	string	Where to apply the new kit. Defaults to "newsroom" when a newsroom is resolvable, otherwise nothing. One of: newsroom, series, nothing.
series	string	Which series: its id, or its exact name. Omit to use the series the user has open (or the only one, if there is one).

Returns

Field	Type	Description
card always	"brand_kit"	What kind of result this is.
brand_kit always	object	The kit that was created, as it was stored.
source_website	string	The site the brand was read from.
identity	object | null	The brand name and tagline found on the page.
applied_to	object | null	Where the kit was pointed, if anywhere.
warning	string	Something partial worth telling the user, usually that the logo could not be downloaded.
refresh	string[]	Which parts of the dashboard this change made stale. In-app only; ignore it.

The kit is saved to the account and, by default, the newsroom is pointed at it. It never becomes the account-wide default; that would silently re-point every other newsroom’s fallback. If the site’s logo cannot be downloaded the kit is still created, with its colours and fonts, and the result says so in warning.

Publishing, running and measuring

update_series_feed

Turn a series' public RSS/MRSS feed on or off, or rebuild it now. Returns the feed's URL.

Parameter	Type	Description
newsroom	string	Which newsroom: its id, or its exact name. Omit to use the one the user currently has open.
series	string	Which series: its id, or its exact name. Omit to use the series the user has open (or the only one, if there is one).
active	boolean
refresh	boolean	Rebuild the feed contents now.

Returns

Field	Type	Description
card always	"feed"	What kind of result this is.
feed always	object	The series' public MRSS feed.
newsroom	object | null	The row this result is about.
series	object | null	The row this result is about.
applied	object | null	The settings that actually landed, keyed by field, with ids resolved to names. Summarise from THIS, not from what was requested. A field missing here did not change.
note	string	Guidance for you, not for the user. Act on it; do not read it out.

run_newsroom_now

Fire a newsroom (or one series) immediately instead of waiting for its schedule. This produces a real video and spends the user's credits. Confirm before calling.

Parameter	Type	Description
newsroom	string	Which newsroom: its id, or its exact name. Omit to use the one the user currently has open.
series	string	Which series: its id, or its exact name. Omit to use the series the user has open (or the only one, if there is one).

Returns

Field	Type	Description
card always	"status"	What kind of result this is.
status always	string	Where the run STARTED. It runs detached, so this is not where it ended.
newsroom	object | null	The row this result is about.
series	object | null	The row this result is about.
run_id	string | null	The run that was queued, when the scheduler returned one.
refresh	string[]	Which parts of the dashboard this change made stale. In-app only; ignore it.

list_newsroom_runs

What a newsroom has actually produced recently: one row per article, with its script and video status and any failure reason.

Parameter	Type	Description
newsroom	string	Which newsroom: its id, or its exact name. Omit to use the one the user currently has open.
limit	number	Rows to return, default 10, max 50.

Returns

Field	Type	Description
card always	"runs"	What kind of result this is.
runs always	object[]	Recent runs, newest first, one row per article a scheduled fire picked up.
newsroom	object | null	The row this result is about.

update_auto_optimization

Turn performance-driven auto-optimisation on or off for a newsroom or one series, and choose which settings it is allowed to vary. Off is byte-identical to how the generator behaved before the feature existed.

Parameter	Type	Description
newsroom	string	Which newsroom: its id, or its exact name. Omit to use the one the user currently has open.
series	string	Which series: its id, or its exact name. Omit to use the series the user has open (or the only one, if there is one).
enabled	string	"true", "false", or (on a series) "inherit" to follow the newsroom.
dimensions	string[]	Which settings it may vary. Defaults to hook_type alone, the one choice nobody ever made deliberately.
exploration_rate	number	Share of videos spent on a non-leading option, 0–0.99. Never 0 in practice: an optimiser that stops exploring cannot notice the audience changed.

Returns

Field	Type	Description
card always	"settings"	What kind of result this is.
applied always	object | null	The settings that actually landed, keyed by field, with ids resolved to names. Summarise from THIS, not from what was requested. A field missing here did not change.
scope	string	Which rung was written: newsroom, newsroom_settings or series.
newsroom	object | null	The row this result is about.
series	object | null	The row this result is about.
deleted	boolean	Present and true when the row was archived.
refresh	string[]	Which parts of the dashboard this change made stale. In-app only; ignore it.

get_newsroom_performance

How a newsroom's published posts are doing: its top posts against the account's own norm, and what auto-optimisation has learned so far. Returns nothing to rank below 5 mature posts, which is the feature working, not a failure.

Parameter	Type	Description
newsroom	string	Which newsroom: its id, or its exact name. Omit to use the one the user currently has open.

Returns

Field	Type	Description
card always	"performance"	What kind of result this is.
series always	object[]	One row per live series, with its optimisation policy when phase D has written one.
newsroom	object | null	The row this result is about.

Refusing to rank is the feature working

Below five mature posts nothing is scored and no policy is written. A newsroom that has just started will report an empty policy for a while; that is correct, not a failure to fetch.

Knowledge bases

A knowledge base is an evergreen subject a newsroom keeps (a product, a person, a place). Its sources (a website, a file, pasted text) are reduced to their text, and Editory keeps one editable brief and a list of angles; every hook and script for the subject is written from the brief and nothing else. Reading one is open to anyone who can see the newsroom; changing it takes the newsroom’s owner or an organization admin. Writing hooks and making a video from them count as reading, exactly as on the page.

list_knowledge_bases

List a newsroom's knowledge bases: the evergreen subjects (a product, a person, a place) it can make videos about from a brief rather than from news. Each row has its brief status, how many angles it has (and how many are still unused), its sources, which series use it and how many videos it has made.

Parameter	Type	Description
newsroom	string	Which newsroom: its id, or its exact name. Omit to use the one the user currently has open.

Returns

Field	Type	Description
card always	"knowledge_list"	What kind of result this is.
knowledge_bases always	object[]	Every knowledge base in the newsroom, oldest first.
newsroom	object | null	The row this result is about.
can_manage	boolean	Whether the caller may change them (owner or org admin).

get_knowledge_base

Read one knowledge base in full: its brief (what it is, who it's for, the key facts, how to talk about it, what never to say, and which fields a person edited), every angle with whether it is switched on and how often it has been used, its sources with their reading status (never their text), the series that use it and the last videos made from it. Read this before changing it.

Parameter	Type	Description
newsroom	string	Which newsroom: its id, or its exact name. Omit to use the one the user currently has open.
knowledge_base	string	Which knowledge base in that newsroom: its id, or its exact name. Omit only when the newsroom has exactly one.

Returns

Field	Type	Description
card always	"knowledge_base"	What kind of result this is.
knowledge_base always	object	The knowledge base as it now stands (the parts this call touched, or all of it on a read).
created	boolean	Present and true when this call created it.
newsroom	object | null	The row this result is about.
applied	object | null	The settings that actually landed, keyed by field, with ids resolved to names. Summarise from THIS, not from what was requested. A field missing here did not change.
note	string	Guidance for you, not for the user. Act on it; do not read it out.
refresh	string[]	Which parts of the dashboard this change made stale. In-app only; ignore it.

create_knowledge_base

Create an empty knowledge base in a newsroom for one evergreen subject. It has no brief until a source is added (add_knowledge_source), so say that and offer to add one: a website, or pasted text.

Parameter	Type	Description
name required	string	The subject, e.g. "Editory Creator app".
newsroom	string	Which newsroom: its id, or its exact name. Omit to use the one the user currently has open.
kind	string	What kind of subject. Default thing. One of: product, person, place, thing.

Returns

Field	Type	Description
card always	"knowledge_base"	What kind of result this is.
knowledge_base always	object	The knowledge base as it now stands (the parts this call touched, or all of it on a read).
created	boolean	Present and true when this call created it.
newsroom	object | null	The row this result is about.
applied	object | null	The settings that actually landed, keyed by field, with ids resolved to names. Summarise from THIS, not from what was requested. A field missing here did not change.
note	string	Guidance for you, not for the user. Act on it; do not read it out.
refresh	string[]	Which parts of the dashboard this change made stale. In-app only; ignore it.

add_knowledge_source

Add a source to a knowledge base: a WEBSITE (read in the background, a minute or more for a whole site; the brief is rewritten when it finishes) or PASTED TEXT (stored now; the brief is rewritten straight away). Pass exactly one of website or text. A file (PDF, Word) cannot be added over chat: tell the user to add it on the knowledge base's page in the newsroom settings.

Parameter	Type	Description
newsroom	string	Which newsroom: its id, or its exact name. Omit to use the one the user currently has open.
knowledge_base	string	Which knowledge base in that newsroom: its id, or its exact name. Omit only when the newsroom has exactly one.
website	string	A web address to read.
scope	string	site (default) reads the whole site, up to 60 pages; page reads only that one page. One of: site, page.
text	string	Text the user pasted: notes, a press release, a spec.
name	string	A name for pasted text. Optional.

Returns

Field	Type	Description
card always	"knowledge_source"	What kind of result this is.
knowledge_base always	object	The knowledge base this result is about.
source always	object	One source of the knowledge base. Its text is never returned.
applied always	object | null	The settings that actually landed, keyed by field, with ids resolved to names. Summarise from THIS, not from what was requested. A field missing here did not change.
deleted	boolean	Present and true when the source was removed.
newsroom	object | null	The row this result is about.
note	string	Guidance for you, not for the user. Act on it; do not read it out.
refresh	string[]	Which parts of the dashboard this change made stale. In-app only; ignore it.

A website is read in the background, page by page, and the brief is rewritten when it finishes; get_knowledge_base shows the progress. A file cannot be added over MCP. It goes in on the knowledge base’s page in the newsroom settings.

remove_knowledge_source

Remove a source from a knowledge base for good (its text goes with it) and rewrite the brief without it. Confirm before calling.

Parameter	Type	Description
source required	string	The source's id, its exact name, or its URL.
newsroom	string	Which newsroom: its id, or its exact name. Omit to use the one the user currently has open.
knowledge_base	string	Which knowledge base in that newsroom: its id, or its exact name. Omit only when the newsroom has exactly one.

Returns

Field	Type	Description
card always	"knowledge_source"	What kind of result this is.
knowledge_base always	object	The knowledge base this result is about.
source always	object	One source of the knowledge base. Its text is never returned.
applied always	object | null	The settings that actually landed, keyed by field, with ids resolved to names. Summarise from THIS, not from what was requested. A field missing here did not change.
deleted	boolean	Present and true when the source was removed.
newsroom	object | null	The row this result is about.
note	string	Guidance for you, not for the user. Act on it; do not read it out.
refresh	string[]	Which parts of the dashboard this change made stale. In-app only; ignore it.

update_knowledge_base

Change a knowledge base: rename it, edit brief fields (a field you set is marked as edited and is kept word for word on every rebuild), switch angles on or off, add the user's own angle, remove an angle the user wrote, or turn "keep it current" (a weekly re-read of its websites) on or off. An angle the brief found can be switched off but never removed.

Parameter	Type	Description
newsroom	string	Which newsroom: its id, or its exact name. Omit to use the one the user currently has open.
knowledge_base	string	Which knowledge base in that newsroom: its id, or its exact name. Omit only when the newsroom has exactly one.
name	string
kind	string	One of: product, person, place, thing.
keep_current	boolean	Re-read its websites weekly.
brief	object	Only the fields to change. Each one named becomes an edited field.
angles	object[]	Switch angles on or off.
add_angle	object	An angle of the user's own.
remove_angle	string	An angle the USER wrote (id or exact name). Found angles can only be switched off.

Returns

Field	Type	Description
card always	"knowledge_base"	What kind of result this is.
knowledge_base always	object	The knowledge base as it now stands (the parts this call touched, or all of it on a read).
created	boolean	Present and true when this call created it.
newsroom	object | null	The row this result is about.
applied	object | null	The settings that actually landed, keyed by field, with ids resolved to names. Summarise from THIS, not from what was requested. A field missing here did not change.
note	string	Guidance for you, not for the user. Act on it; do not read it out.
refresh	string[]	Which parts of the dashboard this change made stale. In-app only; ignore it.

A brief field you write is marked as edited and is carried over word for word on every rebuild. An angle the brief found can be switched off but not removed; only an angle a person wrote can be.

rebuild_knowledge_brief

Rewrite a knowledge base's brief from all of its sources (about a minute, in the background). Fields a person edited are kept word for word, and angles are only ever added, never removed.

Parameter	Type	Description
newsroom	string	Which newsroom: its id, or its exact name. Omit to use the one the user currently has open.
knowledge_base	string	Which knowledge base in that newsroom: its id, or its exact name. Omit only when the newsroom has exactly one.

Returns

Field	Type	Description
card always	"knowledge_base"	What kind of result this is.
knowledge_base always	object	The knowledge base as it now stands (the parts this call touched, or all of it on a read).
created	boolean	Present and true when this call created it.
newsroom	object | null	The row this result is about.
applied	object | null	The settings that actually landed, keyed by field, with ids resolved to names. Summarise from THIS, not from what was requested. A field missing here did not change.
note	string	Guidance for you, not for the user. Act on it; do not read it out.
refresh	string[]	Which parts of the dashboard this change made stale. In-app only; ignore it.

find_knowledge_angles

Ask for up to five NEW angles on a knowledge base's subject, written from its brief and added to its list (about ten seconds). Existing angles are untouched.

Parameter	Type	Description
newsroom	string	Which newsroom: its id, or its exact name. Omit to use the one the user currently has open.
knowledge_base	string	Which knowledge base in that newsroom: its id, or its exact name. Omit only when the newsroom has exactly one.

Returns

Field	Type	Description
card always	"knowledge_base"	What kind of result this is.
knowledge_base always	object	The knowledge base as it now stands (the parts this call touched, or all of it on a read).
created	boolean	Present and true when this call created it.
newsroom	object | null	The row this result is about.
applied	object | null	The settings that actually landed, keyed by field, with ids resolved to names. Summarise from THIS, not from what was requested. A field missing here did not change.
note	string	Guidance for you, not for the user. Act on it; do not read it out.
refresh	string[]	Which parts of the dashboard this change made stale. In-app only; ignore it.

Making a video from a knowledge base

write_knowledge_hooks

Write three opening hooks for a video from a knowledge base, scored, with Editory's pick marked. With no angle, the three freshest switched-on angles get one hook each; with an angle, all three take it. Show the user all three (mark the pick as Editory's pick) and let them choose. Writing hooks makes nothing and spends no video credits.

Parameter	Type	Description
newsroom	string	Which newsroom: its id, or its exact name. Omit to use the one the user currently has open.
knowledge_base	string	Which knowledge base in that newsroom: its id, or its exact name. Omit only when the newsroom has exactly one.
angle	string	One angle (id or exact name) for all three hooks. Optional.
steer	string	A direction from the user, e.g. "aim it at teachers". Optional.
series	string	The series the video will go under (id or exact name). Optional; when that series is auto-optimised, Editory's pick leans toward the hook type it is testing.

Returns

Field	Type	Description
card always	"knowledge_hooks"	What kind of result this is.
hooks always	object[]	Three opening hooks. Pass them back to start_knowledge_video unchanged.
pick always	number	The index of Editory's pick: the strongest hook that stays true to the brief.
newsroom	object | null	The row this result is about.
knowledge_base	object	The knowledge base this result is about.
steer	string	The steer the hooks were written with.
next_step	string	Guidance for you, not for the user. Act on it; do not read it out.

start_knowledge_video

Start a video from a knowledge base with the hook the user chose from write_knowledge_hooks: the script is written from the brief alone and opens on that hook, and (unless video is false) the AI-narrated video is made from it straight after, in the background. The row appears in the newsroom's table. This spends the user's credits. Confirm before calling.

Parameter	Type	Description
hooks required	object[]	The hooks array from write_knowledge_hooks, exactly as it was returned.
chosen required	number	The index of the hook the user chose.
newsroom	string	Which newsroom: its id, or its exact name. Omit to use the one the user currently has open.
knowledge_base	string	Which knowledge base in that newsroom: its id, or its exact name. Omit only when the newsroom has exactly one.
pick	number	Editory's pick, from write_knowledge_hooks.
steer	string	The steer the hooks were written with, if any.
series	string	Which series' row it goes under (id or exact name). Omit for the newsroom's first series.
video	boolean	true (default) also makes the AI-narrated video; false writes the script only, for someone who will record it.

Returns

Field	Type	Description
card always	"knowledge_video"	What kind of result this is.
script_id always	string	The script being written.
status always	string	Where it STARTED. Both run detached, so check get_generation_status rather than trusting this.
newsroom	object | null	The row this result is about.
knowledge_base	object	The knowledge base this result is about.
run_id	string	The newsroom row this video sits on.
job_id	string | null	The video, made once the script lands. null when only the script was started.
applied	object | null	The angle and hook that went out, whether it was Editory's pick, and whether a video was queued.
note	string	Guidance for you, not for the user. Act on it; do not read it out.
refresh	string[]	Which parts of the dashboard this change made stale. In-app only; ignore it.

The user chooses the hook

Show all three hooks, with Editory’s pick marked, and wait for the user to choose. Pass the hooks back to start_knowledge_video exactly as write_knowledge_hooks returned them. Starting the video spends credits.

To have a series make these videos on its schedule, point it at the knowledge base with update_series (knowledge_base); "none" points it back at the newsroom’s own stories.