Almost every tool takes a
brand_id. Start a session with rheos_get_capabilities, then rheos_list_brands to get valid brand_id values, then rheos_get_brand_context to load the brand voice, audiences, themes and connected platforms in one call. Use the brand_id that rheos_list_brands returns; never guess one.Posts
One tool per record type for posts, pillars, assets and creative sessions. The tool name picks the collection, so none of them takes aresource_type.
rheos_list_posts
List the organisation’s posts — drafts, ideas, scheduled and published — newest first.
brand_id(optional) — filter to one brandstatus(optional) — e.g."draft","idea","scheduled","published"."published_or_partial"lists every post that went out, most recently published first.limit(optional) — default 10, max 50fields(optional) — return only these fields; pass["textBody"]to include the post text, which is left out by defaultcursor(optional) — from the previous response, for the next page
fields name that no post has is refused with unknown_fields, and the
response lists the names that work. title is returned as name and
platforms as channels. The same refusal applies to fields on
rheos_list_pillars, rheos_list_assets and rheos_list_sessions.
Each post carries published_links (one per channel it went out on, with its
url and live_status), published_at and dashboard_url. A link’s url is
null until Rheos has it. Instagram links are usually there as soon as the
post publishes. Otherwise they can take a few hours.
rheos_list_pillars
List content pillars — the brand’s recurring topics and angles — newest first.
Takes the same brand_id, status, limit, fields and cursor as rheos_list_posts.
rheos_list_assets
List the Library — uploaded and generated images and videos — newest
first. Takes the same parameters as rheos_list_posts, plus:
include_deleted(optional) — set totrueto include soft-deleted assets; defaults tofalse
rheos_list_sessions
List creative sessions (image, video, carousel) newest first. Takes brand_id,
status, limit and fields, plus:
session_type(optional) — narrow to one type; omit to list every type
cursor paging for sessions.
rheos_get_post
Fetch one post by id, with its full text, channels, status and publish results,
plus published_links, published_at and dashboard_url.
idorpost_id— the record id. Pass one of them;post_idis accepted because the publishing tools use that name.brand_id(optional) — checks the record belongs to that brand; a mismatch is rejectedfields(optional) — return only these fields
rheos_get_pillar
Fetch one content pillar by id. Same parameters as rheos_get_post, with
pillar_id in place of post_id.
rheos_get_asset
Fetch one Library asset (image or video) by id. Same parameters as
rheos_get_post, with asset_id in place of post_id. Soft-deleted assets
are not returned.
rheos_get_session
Fetch one creative session by id. Same parameters as rheos_get_post, with
session_id in place of post_id, plus an optional session_type. Pass
it if you know it; otherwise every type is searched.
rheos_post_interview
Start here for any new post. It runs the post interview the Rheos app runs
before it drafts a post, one turn per call. Each result is one question for the
person. The assistant asks it exactly as given, then waits for the answer.
The tool asks the setup itself: who the post speaks as (where that applies),
the platforms, the format for each platform that offers more than one, and the
goal. Then it asks what the post is about, with a few topic ideas, and only
asks for facts the draft would otherwise invent. A photo post gets its picture
next. When status is "finished", the result holds the brief and the
save_with fields for rheos_create_post.
brand_id(optional) — the business brand. Omit it when the account has one business. With several, the organisation’s default business is used.platforms(optional) — every platform the person picked, first one first. Leave it out until they have picked: the tool asks.answers(optional) — every answer so far: theanswerslist the last result gave, plus the person’s answer to its questionfrom_slot(optional) — a slot fromrheos_list_open_slots. The slot settles the platform and the goal.asset_ids(optional) — photos already chosen for the postskip(optional) —trueto write the post now with what is knownsuggest(optional) —truefor topic ideas instead of a question
needs_a_person. The assistant then asks the questions itself.
rheos_create_post
Draft a post. The assistant writes the text; this saves it as a draft the user
reviews, schedules or publishes from Rheos.
brand_id— required unless you passslot_idfields—textBody(required unlessstatusis"idea"), plus optionalname,channels,assetIds,tags,pillarIds,status("draft"by default, or"idea"),notes(the brief: what the post is about and why, in a sentence or two),postType("text"or"visual"),brandMode("business"or"personal", defaulting to the brand’s own type) andsubjectBrandId(personal brands only: the business brand the post is about)fields.platformSettings.instagram(optional, Instagram only) —trialGraduation("MANUAL"or"SS_PERFORMANCE", for a trial reel from one video),aiGenerated(trueadds Instagram’s AI label),shareToFeed(falsekeeps a reel in the Reels tab),collaborators(up to 3 Instagram usernames, without the @),contentType("post"or"story"),coverAssetId(an image asset to use as the reel cover),thumbOffsetMs(the frame to use as the reel cover, in milliseconds) andaltText(alt text for each image, keyed by asset id)context(optional) — inspiration to keep beside the post. It is never published. Pass up to 5notes(each up to 2,000 characters), up to 10asset_idsfrom the Library and up to 5links.slot_id(optional) — a slot fromrheos_list_open_slots. The post fills that slot, and the slot sets its brand, platform, funnel stage and date.captions(optional) — with several platforms inchannels, each platform’s own text, keyed by channel id, for example{"linkedin_org": "...", "twitter": "..."}. A platform with no caption getstextBody.
channels takes instagram, facebook, linkedin, linkedin_org (a
LinkedIn company page) or twitter (X). For a new post, the assistant runs
rheos_post_interview first and saves its finished result here.
One call can save a post for several platforms. Rheos saves one post per
platform and links each copy to the first. The editor shows them as one post
with a tab per platform. The response lists every post in post_ids, the main
post first. Scheduling and publishing still go one post id at a time.
LinkedIn has two variants. A business brand posts to a LinkedIn company page
with linkedin_org, and a personal brand posts to a LinkedIn profile with
linkedin. The variant follows the brand, so a mismatch is refused with
linkedin_variant_mismatch.
intent and hookId fields are still accepted and optional.
rheos_create_pillar
Create a content pillar — a recurring topic or angle for the brand.
brand_id(required)fields—name, plus optionalintent,hookId,audiences,themes,colorandicon
rheos_update_post
Patch fields on an existing post. Use this after rheos_turn_idea_into_draft to
write the post body, or to edit a draft before scheduling.
id,fields— partial update objectbrand_id(optional) — rejects a post stored under a different brand
fields.channels changes, it still holds one platform. Use linkedin_org for a business brand and linkedin for a personal one. A mismatch is refused with linkedin_variant_mismatch.
fields.status can be "draft", "idea" or "archived". Scheduling and publishing go through the publishing tools below.
rheos_update_pillar
Edit a content pillar’s name, intent, audiences, themes, colour or icon. Same
parameters as rheos_update_post.
rheos_update_asset
Edit a Library asset — rename it, re-tag it, change its notes, or move it to a
different brand (fields.brandId). Same parameters as rheos_update_post.
Copy, archive and restore posts
These three tools take apost_id and nothing else. The post’s own brand
applies, so they take no brand_id. An expected refusal, such as a live or
scheduled post, comes back as ok: false with an error and a message.
rheos_duplicate_post
Copy a post into a new draft on the same platform, to reuse it. It works on a
post in any status, a published one included. The copy keeps the text, media,
brand, hashtags and settings. It starts with no schedule, no publish history and
no plan slot, and its name ends “(copy)”. It never changes platform.
post_id(required) — the post to copy
post_id, copied_from, name, channels and status: "draft".
rheos_archive_post
Archive an idea, draft or failed post that is not live, to take it out of the
way. It can be restored.
post_id(required) — the post to archive
rheos_duplicate_post instead, or remove it on the platform and
Rheos archives it. A scheduled post needs its schedule cancelled first, with
rheos_cancel_scheduled_post.
rheos_restore_post
Bring an archived post back as a draft. It works only for a post that never
went live. A post that was published and is gone from its platform stays
archived: reuse it with rheos_duplicate_post.
post_id(required) — the archived post to restore
rheos_archive_post and rheos_restore_post return the post_id, its new
status and changed, which is false when there was nothing to do.
Ideas
Ideas live as posts withstatus="idea"; accepting one flips it to
status="draft".
rheos_brainstorm_post_ideas
Brainstorm four post ideas in the brand’s voice, each with a different hook and
intent. Pick one, write the body yourself, then save it with rheos_create_post.
prompt(required) — the topic, idea or briefbrand_id(optional) — defaults to the organisation’s primary brandchannels,current_text(optional) — shape the ideaspost_length(optional) —one-liner,short,mediumorlongintent(optional) —sell,educate,prove,connect,provoke,inspire,announceorentertainhook_type,audience_name,theme_title(optional) — bias the ideas
rheos_add_ideas_to_plan
Brainstorm new ideas and save them as posts with status="idea". Returns their
idea_ids. Use when you want the user to pick from a queue rather than
brainstorm inline.
brand_id(required)prompt(optional) — what to brainstorm aboutcount(optional) — 1 to 8, default 3channels,intent,hook_type,audience_name,theme_title(optional) — bias the set
theme_title that is the name of one of the brand’s pillars (see
rheos_list_pillars), or one of a pillar’s themes, also saves the ideas on
that pillar. Case and surrounding spaces are ignored. No pillar is saved when
nothing matches or two pillars match equally. When you pass theme_title, the
response includes pillar_id, which is null when no pillar matched. Saved
ideas are not in a plan slot: they have no date and no funnel stage.
rheos_turn_idea_into_draft
Flips one idea from status="idea" to status="draft". After accepting,
write the body in the brand voice and save it via rheos_update_post.
idea_id(required)
pillar_ids and
on_plan. on_plan is false unless the idea was already on the plan. Then
next_step says how to place the draft: call rheos_list_open_slots, then
copy a slot’s stage and date onto the draft with rheos_update_post
(funnelStage, inPlan: true and scheduledAt). The slot counts the draft
when the draft is on the slot’s channel.
Strategy and plan slots
A brand’s content strategy sets its goal, how many posts it needs each week and on which platforms. These tools read it; changing the strategy happens in the Rheos dashboard.rheos_get_strategy
Read one brand’s content strategy: its goal, the minimum posts a week for each
funnel stage, its cadence (posts a week and platforms), pillars and series.
exists: false means the brand has no strategy yet, and the response shows the
defaults.
brand_id— the business brand. On an account with one business you can leave it out. With several, the call is refused withbrand_id_requiredand abusinesseslist (nameandbrand_id), so you can ask the user which one.brand_mode(optional) —"personal"reads the strategy your personal brand posts into
brand_id and brand_name of the brand whose plan it
is. When a personal brand’s read lands on a business’s plan, scope_note comes
first and says so.
rheos_list_strategies
Every brand in the organisation with its strategy. A brand without one returns
exists: false and the defaults. unreadable: true means the brand’s
strategy could not be read, so the defaults shown are not its real plan. Takes
no parameters.
rheos_list_open_slots
The week’s open slots: the posts the strategy still needs. Each slot has a
slot_id, a date, a funnel stage (tof awareness, mof consideration,
bof conversion), a piece (video, carousel, or null for any post),
an account (the brand and channel it posts from), a format (such as image or carousel) and a slot_key.
A slot may also carry the plan’s pick of what its post is about: a pillar
(id, name) and a topic (id, name, optional angle). Both are absent
when the brand has no content pillars. topic is absent when the pillar has no
topics. The assistant offers them as a starting point, and the user can change
them.
brand_id(optional) — the business brand whose strategy to read; defaults to the organisation’s strategyweek(optional) — the Monday of the week,yyyy-MM-dd; defaults to this weekbrand_mode(optional) —"personal"reads the strategy your personal brand posts into
slot_id, exactly as returned, to
rheos_create_post. A filled slot no longer appears, and past days have no
slots. exists: false means the brand has no strategy yet.
Publishing
Move a draft to scheduled or live. A post goes to one platform. Scheduling and publishing are real actions on the brand’s connected social accounts, so the assistant should confirm with the user first.rheos_schedule_post, rheos_publish_post and rheos_cancel_scheduled_post need publishing access. An API key has it only if Allow publishing was selected when the key was created.rheos_schedule_post
Queue a post for a future time. Status moves to scheduled, and Rheos
publishes it at scheduled_at, even if the chat is closed. The post publishes
to the channels already set on the draft.
post_id(required)scheduled_at— an ISO 8601 timestamp in the future
rheos_list_connected_accounts (or rheos_get_brand_context) to see which channels are
connected. Use rheos_get_connect_link to connect any missing channel before
retrying.
Scheduling can also be refused with these errors:
media_required: the post has no image or video attached. Instagram needs one.weekly_quota_exceeded: the account’s weekly post limit has been reached.already_scheduled: the post is already scheduled.linkedin_page_not_chosen: the brand’s LinkedIn company connection has more than one Page and none is chosen. Reconnecting does not fix it. The user picks a Page in Settings → Social Accounts, then the assistant schedules again.
If Rheos cannot check, the post is scheduled anyway; it fails at publish time instead. It blocks only when a channel is definitely not connected.
rheos_publish_post
Publish immediately to the channels set on the draft. This is a real action:
the post goes out on the brand’s connected social accounts straight away.
Returns per-channel publishResults. Inspect results[].error if any channel
fails.
post_id(required) — a post with statusdraftorscheduledforce(optional) — publish even if identical content was recently published from a different post
next_step (or hint) says how to retry:
- Failed: set it back to draft with
rheos_update_post(fields: { status: "draft" }), then callrheos_publish_postagain. - Partly published: copy the post with
rheos_duplicate_post, remove the channels that already went live from the copy withrheos_update_post, then callrheos_publish_poston the copy. Publishing the original again would repost the channels that are already live.
reconnect list. Get a link with rheos_get_connect_link first.
Publishing is refused up front with linkedin_page_not_chosen when the
brand’s LinkedIn company connection has more than one Page and none is chosen.
Nothing is posted. The user picks a Page in Settings → Social Accounts,
then the assistant calls rheos_publish_post again.
rheos_cancel_scheduled_post
Pull a scheduled post back to draft so you can edit or delete it.
post_id(required)
rheos_get_connect_link
Returns a dashboard link the user opens in a browser to connect a social
account. It does not connect anything by itself: the response status is
url_handoff_required until the user finishes in the browser.
brand_id(required)channel— the platform to connect:instagram,facebook,linkedin,linkedin_orgortwitterbrand_mode(optional) —"business"(default) or"personal"
channel_not_for_this_brand, and no link is made. A business takes
linkedin_org, not linkedin. A personal brand cannot take instagram,
facebook or linkedin_org.
Brands and identity
Read a brand’s voice, identity document and sources, create a new business brand, and export its kit.rheos_list_brands
List every brand in the org (both business and personal). Call this at the
start of any drafting flow, after rheos_get_capabilities. Every later tool
needs a brand_id, and this is where valid ones come from.
fields(optional) — extra details for each brand:website_url,industry,country,taglineorcontact_email
rheos_get_brand_context
Bundle call: returns the brand voice and banned phrases, the identity
document, pillars, audiences, themes and connected platforms in one response.
Audiences come from audience boxes or the content strategy, with legacy
pillars as the last-resort fallback. Themes come from the brand’s active
pillars. Archived pillars are left out of the pillars list. The
audiences and themes fields remain arrays of strings, with empty and
whitespace-only values omitted.
brand_id(optional) — defaults to the organisation’s primary brand
rheos_create_brand
Create a new business brand. It starts with empty identity fields, ready to
fill in with the tools under Fill in a brand. Returns the
new brand_id.
brand_name(required) — 1 to 80 characterswebsite_url(optional) — saved on the new brand
website_url is refused with invalid_arguments, and nothing is
created. A name the account already uses for a business is refused with
brand_name_taken, which returns that brand’s brand_id. Case and spaces are
ignored when names are compared.
rheos_get_brand_document
Read the freeform markdown identity document for a brand — the synthesised
output of all sources. The response includes a rev to pass to
rheos_edit_brand_doc as expected_rev. A brand with no document yet returns
brand_document_not_found with a rev to write the first one against.
brand_id(optional) — defaults to the organisation’s primary brand
rheos_list_brand_sources
List every source attached to the brand (website scrape, AI import, uploaded
docs) with status and timestamps.
brand_id(optional) — defaults to the organisation’s primary brand
rheos_get_brand_source
Read the full content of a single source, in windows of a set length.
source_type(required) —"website","ai_import"or"document"document_id— required whensource_typeis"document"; fromrheos_list_brand_sourcesprovider(optional, for"ai_import") —claude,chatgpt,perplexityorgeminibrand_id(optional) — defaults to the organisation’s primary brandmax_chars,offset(optional) — when the response saystruncated: true, pass itsnext_offsetasoffsetto read on
rheos_update_ai_import
Save what the assistant knows about a brand, in the person’s own words, as an
AI import brand source. Use it to set up a brand with no website. The assistant
asks what the business does, who it serves, what it sells and how it sounds,
one question at a time. It saves the answers here, then calls
rheos_trigger_identity_doc_flow to write the brand document from them. That
takes about 30 seconds.
Each assistant has its own slot, so one import never overwrites another’s. The
slot’s earlier content is kept as a version (versioned_previous). The
response returns the slot and a next_step.
Once a brand document exists, the import does not change it. The user reviews
the import on the brand page in Rheos and pulls anything new into the brand.
content(required): the brand description, in markdownsource(optional): which assistant wrote it, in lower case. Defaults toclaude.claude,chatgpt,perplexityandgeminieach get their own slot; anything else shares one.brand_id(optional): defaults to the organisation’s default businessbrand_mode(optional):"personal"targets a personal brand, withuser_id
rheos_export_brand_kit
Export the brand’s creative kit and voice for an image or video generator
outside Rheos. Returns a JSON context (palette, fonts, logo URLs, website,
social handles, voice) and a prompt_block to paste into the generator.
Read-only.
brand_id(required)
rheos_import_asset_from_url.
Fill in a brand
Write a brand’s details, offerings and audiences — the same brand details you see in the Rheos dashboard. Passbrand_id on every call.
Each add tool returns the new item’s
id. The update, remove, archive and unarchive tools take that id, or the item’s exact name.name can be up to 120 characters, and its
description up to 600. This applies to every add and update tool, including
each entry in items. A longer value is refused.
rheos_update_brand_metadata
Set a brand’s structured details. Only the fields you pass change, and Rheos
keeps these values when it next updates the brand from its sources. Returns the
full updated set. It does not change the brand’s name.
brand_id(required)brand_mode(optional) —"business"(default) or"personal"fields— any oftagline,mission,industry,sub_industry,website_url,country(two-letter code),founded_year,company_size(solo,1-10,11-50,51-200,201-1000or1000+),legal_entity,contact_email,phone_numberandsocial_handles
rheos_add_offering
Add something the brand sells, or a reason it stands out. Business brands only.
brand_id(required)name— the offering’s short name. Leave it out when you passitems.description(optional) — one or two sentenceskind(optional) —"offering"(default) for a product or service,"differentiator"for a reason it stands outstatus(optional) —planned,liveorretireditems(optional) — several offerings in one call, up to 20, each with its ownname,description,kindandstatus. Use it instead ofname.
items, a name the brand already has is skipped. The response lists each
item as created, skipped_existing or error, with counts.
rheos_update_offering
Change an offering. Only the fields you pass change.
brand_id(required)id(required) — the offering’sid, or its exact namename,description,kind,sortOrder(optional)status(optional) —planned,liveorretired
rheos_remove_offering
Delete an offering. This is permanent.
brand_id(required)id(required) — the offering’sid, or its exact name
rheos_add_audience
Add an audience the brand serves: who they are and, if known, their pains
(problems) and desires (goals). Works on business and personal brands.
brand_id(required)name— e.g. “Independent cafés”. Leave it out when you passitems.description(optional)pains,desires(optional) — lists of short phrasesitems(optional) — several audiences in one call, up to 20, each with its ownname,description,painsanddesires. Use it instead ofname.
items, a name the brand already has is skipped, and each item’s outcome
is returned.
For your personal brand, pass brand_mode: "personal" instead of brand_id.
That works only when you connected by signing in: an API key belongs to the
organisation, not to a person.
rheos_update_audience
Change an audience. Only the fields you pass change.
brand_id(required)id(required) — the audience’sid, or its exact namename,description,pains,desires,sortOrder(optional)
pains and desires each replace the whole list. Call rheos_list_audiences
first and send the full list, including the items you keep.
rheos_archive_audience
Hide an audience from the brand’s active list. It is not deleted:
rheos_unarchive_audience brings it back.
brand_id(required)id(required) — the audience’sid, or its exact name
rheos_unarchive_audience
Restore an archived audience to the active list.
brand_id(required)id(required) — the audience’sid, or its exact name
Brand style and brand document
Change a business brand’s look and its brand document — the Style tab and the brand document you see on the brand page in Rheos. These tools work on business brands only, and a personal brand is refused. The exception isrheos_edit_brand_doc, which can also edit your own personal brand’s document.
rheos_update_brand_style
Change a brand’s palette colours, heading and body fonts, visual direction
notes and style chips. Rheos uses them for every on-brand image it generates.
Only what you pass changes; logos and every other slot stay as they are.
brand_id(required) — a business brand fromrheos_list_brandspalette(optional) — any ofprimary,secondary,accent,backgroundandtext, each a hex code (#RRGGBBor#RGB)typography(optional) —heading_fontand/orbody_font, as font family names (ideally Google Fonts, e.g."Inter")visual_direction(optional) — free-text notes on photography style, mood and what to avoid; replaces the current notes, and""clears themstyle_tags(optional) — the complete set of style chips; replaces the current set, and[]clears it. Only the Style tab’s own chips are accepted.
no_fields_provided. The
response lists each change with its before and after value. Colour, font
and notes changes can be undone from History on the brand page.
rheos_set_brand_logo
Set a brand’s logo from an image already in that brand’s Library. Upload the
file with rheos_upload_image first, then pass the asset_id it returns.
brand_id(required) — a business brand fromrheos_list_brandsasset_id(required) — an image asset uploaded for this brandslot(optional) —"logo"(default) adds it to the brand’s logos,"primary_logo"makes it the main logo,"icon"sets the small square site icon
rheos_upload_image takes PNG, JPEG
and WebP only. Calling it again with the same asset and slot changes nothing.
rheos_edit_brand_doc
Edit the brand document in two steps. Nothing is saved until the person
confirms.
doc(required):"identity"for the brand documentbrand_id(optional): a business brand. Or passaccount"personal"for your own personal brand. Leave both out to use the connection’s active brand.
expected_rev (required): the rev from
rheos_get_brand_document, or current.rev from
rheos_list_brand_document_versions. Then pass one of:
patch: edits applied in order, all or nothing. The ops arereplace(old_string,new_string, optionalreplace_all),insert_beforeandinsert_after(anchor,text),prependandappend(text), andreplace_range(from,to,new_string). Every anchor must match the current text exactly once.content: the complete new document, replacing the old one
patch_invalid. An optional change_summary
(one line, up to 200 characters) shows with the proposal and in the version
history. An optional operation_id (8 to 100 letters, digits, _ or -)
makes a retry with the same id return the first answer instead of acting
twice. The response describes what would change and returns a proposal_id
and apply_with. The document is not changed yet.
Step 2, apply. Show the person what would change. Once they agree, call
the tool again with only the apply_with arguments. It saves exactly the
proposed text as a new version. A proposal works once and expires after 30
minutes. It is refused as stale, with current_rev, if the document changed
after you read it or proposed. Read it again and propose again.
A rev is <version>.<content hash>, so it also catches an edit saved on the
brand page without a new version.
rheos_update_brand_document
Edit the brand document in two steps. Nothing is saved until the person
confirms.
Step 1, propose. Pass brand_id and one of:
edits— find/replace changes applied in order. Eachfindmust match the current text exactly once, unless you setreplace_all: true.markdown— the complete new document, replacing the old one
base_version or base_hash from
rheos_list_brand_document_versions, so the proposal is refused if someone
changed the document since you read it. An optional change_summary (one
line) shows with the proposal and in the brand page’s version history. The
response describes what would change and returns a proposal_id. The
document is not changed yet.
Step 2, apply. Show the person what would change. Once they agree, call
the tool again with only brand_id and proposal_id. It saves exactly the
proposed text as a new version. A proposal works once, expires after 30
minutes, and is refused if the document changed after it was proposed —
propose again in that case.
It edits business brands only, never a personal brand. It refuses edits that
would leave the document empty or make it longer than 200,000 characters.
rheos_list_brand_document_versions
List the brand document’s versions: the current one and the archived ones
before it, newest first. Every edit, from Rheos or from the connector, archives
the text it replaced. Use it to get the current rev (current.rev) for
rheos_edit_brand_doc, the current version and content_hash for
rheos_update_brand_document, or a version_id to restore.
brand_id— a business brand fromrheos_list_brandslimit(optional) — archived versions to return, default 10, max 50include_markdown(optional) —truereturns the full text of each version, not just a preview
rheos_restore_brand_document_version
Bring back an earlier version of the brand document. The restored text is
saved as a new version and the text it replaces is archived first, so a
restore can itself be undone the same way.
brand_id— a business brand fromrheos_list_brandsversion_id(required) — fromrheos_list_brand_document_versionsbase_version,base_hash(optional) — refuse the restore if the document changed since you read itchange_summary(optional) — one line saying why, shown in the version history
Images and video
Generate, iterate, upload and save images, and bring in video. Saved assets get anasset_id you pass into rheos_create_post as assetIds.
Asset read responses omit the raw
embedding vector. Soft-deleted assets are excluded by default; set include_deleted: true on rheos_list_assets when you need to include them.rheos_generate_image
Generate or iterate an image inside a session. The image shows in the chat, so
the assistant can check it and try again. Pass iterate_from_generation_id to
refine instead of starting fresh.
prompt(required)brand_id(optional) — the brand whose identity, palette and logos shape the image; defaults to the organisation’s primary brandpost_copy(optional) — the post’s text, so the image is composed to fit itcount(optional) — 1 to 4 options, default 1mode(optional) —gpt-image-2(default),normalorpro. Aproimage counts as two toward the account’s monthly image allowance.aspect_ratio(optional) —"1:1"(default),"4:5","9:16"or"16:9"session_id(optional) — resume an existing sessioniterate_from_generation_id(optional)reference_asset_ids,reference_image_urls(optional) — images to use as references. Up to 4 reference image URLs, each PNG, JPEG or WebP and 10 MB or less.
rheos_read_documentation with the
images.allowance topic says what the assistant can do instead.
rheos_save_image_to_library
Promote a generation into the brand’s Library so it can be attached
to a post.
session_id,generation_id— from the previousrheos_generate_imagecallname,tags(optional)
rheos_get_image_session
Read back every image generated in a session — the options themselves, their
prompts, and which ones were kept. Use it when the generation response has
scrolled out of the conversation: without it the only way to see those options
again is to generate them again.
session_id(required) — fromrheos_generate_imagelimit(optional) — newest first, default 20, max 50
generation_id, image_url, prompt, status and
saved_asset_id (set once promoted). The response also carries a markdown
field of image links, so an assistant whose interface drops inline images can
still show the options.
rheos_upload_image
Store an image (PNG / JPEG / WebP, ≤10 MB) in the Library. Returns an
asset_id.
brand_id(required)image_urlorimage_base64— useimage_base64only for a small image, about 100 KB or lesspost_id(optional) — attach the image to an existing draft in the same callalt_text,filename,source_note(optional)
rheos_upload_video
Store a video (MP4, MOV or WebM, up to 25 MB) in the Library. Returns an
asset_id you pass to rheos_create_post as assetIds.
brand_id(required)video_base64orvideo_url— exactly onealt_text,filename,source_note(optional)
rheos_import_asset_from_url
Import an image or video made in another generator into the Library, and
record where it came from. Images up to 10 MB, videos up to 25 MB. Returns an
asset_id.
url(required) — the http(s) link to the image or videobrand_id(required)post_id(optional) — attach the asset to an existing draft in the same callname,tags(optional)metadata(optional) —provider,model,jobId,costandprompt, stored on the asset
rheos_draft_post_from_image
One-shot: upload an image and draft a caption + post in a single call.
Preferred over rheos_upload_image + rheos_create_post when the user already
has a topic in mind.
brand_id(required)image_base64orimage_urltopic(required) — what the post should be aboutchannels(optional) — pass one platform, for example["instagram"]. If you leave it out, the draft uses the brand’s one connected platform; when several are connected, Rheos asks which one first.alt_text,filename,source_note(optional)
Search
rheos_search_posts
Search a brand’s posts — drafts, scheduled, published and imported — by
meaning and by exact text. Use it to check “have we already posted something
like this?” before drafting. Meaning matches come first. Each result says
whether it matched on "meaning" or "text".
brand_id(optional) — without it, the account’s default business brand is searchedquery(required) — a topic or idea, or exact words from the poststatus(optional) — filter by post status;"published_or_partial"matches every post that went outpublished_after,published_before(optional) — ISO dateslimit(optional) — default 10, max 50
truncated: true means older posts were not text-searched.
rheos_search_assets
Basic text matching against the Library (name, description, tags).
Soft-deleted assets are excluded. Every matching result includes its own
score.
query(required)brand_id(optional) — without it, the whole organisation’s Library is searchedlimit(optional) — default 10, max 20
Reference
Small helpers split out so they don’t bloatrheos_get_brand_context.
rheos_get_capabilities
Report which capabilities are usable right now — such as image generation,
uploads and publishing — before committing to a workflow. Cheap, read-only,
and makes no outbound calls.
brand_id(optional) — publishing readiness is brand-scoped; defaults to the org’s primary brand
granted (is it on your tool surface), healthy (is
it usable this moment) and a plain-language reason when either is false.
For example: no connected channel, an image allowance that is used up, or a
key or sign-in without publishing access. Publishing shows granted: false
for a key created without Allow publishing.
Call it first and you avoid discovering a limit by hitting an error mid-task.
rheos_fetch_docs
Read these docs (docs.rheos.app) so the assistant can answer “how does Rheos
do X?” without guessing. Read-only.
url(optional) — a docs path such as/developers/mcp/tools, or a docs.rheos.app URL. Omit it to get the docs index: every page with its title and link.
rheos_read_documentation has a short answer without
fetching a page.
rheos_read_documentation
The documentation for the person’s Rheos account and the settings around it.
The assistant reads it when a setting blocks it, when it worked around one, or
when the person asks how to set something up. Each page says what is true now,
what the person changes and where in Rheos, and what the assistant can still
do. Read-only.
situation(required) —"blocked"(the assistant cannot finish what was asked),"worked_around"(it finished another way) or"asked"(the person asked how to set this up)topic(optional) — the page to read. Leave it out to list the pages and when each applies.
A page returns its
guidance, a how_to_use note for the situation, and,
where one fits, a settings_url in the Rheos dashboard and a help_url on
these docs.
rheos_list_audiences
Return the brand’s active audiences, and where they came from.
brand_id(optional) — without it, you get the older organisation-wide list
name is required on each audience. description is optional. With a
brand_id and source "audience_boxes", each audience also has its id,
and pains and desires are always lists, empty when it has none.
archived_audiences names the brand’s archived audiences, and appears only
when it has some. With any other source, pains and desires are optional.
source is "audience_boxes" | "content_strategy" | "legacy_pillars" | "none". It identifies current audience boxes, the content
strategy, the legacy pillars fallback, or no data.
rheos_list_content_themes
Return the brand’s themes, and where they came from. A brand’s themes are its
active pillars, by name and description. Archived pillars are left out.
brand_id(optional) — without it, you get the active pillars across the organisation
title is required on each theme. description is optional.
source is "pillars" | "none": the brand’s pillars, or no data.
rheos_list_connected_accounts
List a brand’s social accounts: which are connected, which can be connected,
and which are unavailable and why. usable: true means a publish would go out
on that channel.
brand_id(optional) — defaults to the organisation’s primary brand
rheos_report_feedback
Your assistant can call this when a Rheos tool returns an error, returns
something wrong, is confusing, is slow or is missing something. Reports go
straight to the Rheos team. Assistants should not include passwords, keys, or
post text the user did not ask to share.
summary(required) — one line, up to 120 characterskind(required) —bug,wrong_result,missing_capability,confusing_descriptionorslowwhat_i_tried(required) — what the user asked for and the calls madeexpected,actual(required) — what should have happened, and what did, including any error messageseverity(required) —blocker,annoyingorideatool(optional) — the name of the tool the report is aboutbrand_id(optional) — the brand involved
received: true and a feedback_id. Any key can call it, including
a key without publishing access. Each organisation can send 20 reports a day.
Past that, the call returns feedback_rate_limited.
Conventions
- Errors include
errorand may includehint,next_step, or tool-specific fields such aschannels. When present,hinttells the caller which tool to invoke next (e.g. “Callrheos_list_brandsfirst”). - All timestamps are ISO 8601 in UTC.
brand_idfor personal brands is the user’suser_id; for business brands it’s the short id fromrheos_list_brands.- Access: an API key can read and write. Scheduling, publishing and cancelling a scheduled post also need publishing access, which a key has only if Allow publishing was selected when it was created.

