Skip to main content
Every tool a Rheos account can use through the connector, with the parameters your assistant needs. There are 66 of them. If you’re an end user, you probably don’t need this — your AI chat picks the right tool automatically. It’s useful if you’re building agent workflows or want to know exactly what’s possible. Each tool returns JSON. The shapes shown below are summaries; call the tool and inspect the response for the full schema.
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 a resource_type.

rheos_list_posts

List the organisation’s posts — drafts, ideas, scheduled and published — newest first.
  • brand_id (optional) — filter to one brand
  • status (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 50
  • fields (optional) — return only these fields; pass ["textBody"] to include the post text, which is left out by default
  • cursor (optional) — from the previous response, for the next page
A 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 to true to include soft-deleted assets; defaults to false

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
There is no 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.
  • id or post_id — the record id. Pass one of them; post_id is accepted because the publishing tools use that name.
  • brand_id (optional) — checks the record belongs to that brand; a mismatch is rejected
  • fields (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: the answers list the last result gave, plus the person’s answer to its question
  • from_slot (optional) — a slot from rheos_list_open_slots. The slot settles the platform and the goal.
  • asset_ids (optional) — photos already chosen for the post
  • skip (optional) — true to write the post now with what is known
  • suggest (optional) — true for topic ideas instead of a question
On every call, send back what the last result asks for, with the answers and research it gave. A connection that is not tied to a person is refused with 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 pass slot_id
  • fields — textBody (required unless status is "idea"), plus optional name, 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) and subjectBrandId (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 (true adds Instagram’s AI label), shareToFeed (false keeps 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) and altText (alt text for each image, keyed by asset id)
  • context (optional) — inspiration to keep beside the post. It is never published. Pass up to 5 notes (each up to 2,000 characters), up to 10 asset_ids from the Library and up to 5 links.
  • slot_id (optional) — a slot from rheos_list_open_slots. The post fills that slot, and the slot sets its brand, platform, funnel stage and date.
  • captions (optional) — with several platforms in channels, each platform’s own text, keyed by channel id, for example {"linkedin_org": "...", "twitter": "..."}. A platform with no caption gets textBody.
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.
The older 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 optional intent, hookId, audiences, themes, color and icon

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 object
  • brand_id (optional) — rejects a post stored under a different brand
Each platform of a post saved for several platforms has its own post id. Pass that platform’s post id to change its text. When 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 a post_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
Returns the new 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
A published, partly published or publishing post cannot be archived by hand. Reuse it with 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 with status="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 brief
  • brand_id (optional) — defaults to the organisation’s primary brand
  • channels, current_text (optional) — shape the ideas
  • post_length (optional) — one-liner, short, medium or long
  • intent (optional) — sell, educate, prove, connect, provoke, inspire, announce or entertain
  • hook_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 about
  • count (optional) — 1 to 8, default 3
  • channels, intent, hook_type, audience_name, theme_title (optional) — bias the set
A 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)
The draft keeps the idea’s pillar. The result includes 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 with brand_id_required and a businesses list (name and brand_id), so you can ask the user which one.
  • brand_mode (optional) — "personal" reads the strategy your personal brand posts into
The response includes the 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 strategy
  • week (optional) — the Monday of the week, yyyy-MM-dd; defaults to this week
  • brand_mode (optional) — "personal" reads the strategy your personal brand posts into
Fill a slot by passing its 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
If any channel set on the post has no connected social account, the call is rejected before scheduling:
Call 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 status draft or scheduled
  • force (optional) — publish even if identical content was recently published from a different post
A post that failed or only partly went out cannot be published again as it is. The response’s next_step (or hint) says how to retry:
  • Failed: set it back to draft with rheos_update_post (fields: { status: "draft" }), then call rheos_publish_post again.
  • Partly published: copy the post with rheos_duplicate_post, remove the channels that already went live from the copy with rheos_update_post, then call rheos_publish_post on the copy. Publishing the original again would repost the channels that are already live.
If a channel failed because its account needs reconnecting, the response includes a 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)
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_org or twitter
  • brand_mode (optional) — "business" (default) or "personal"
A channel the brand’s type cannot have is refused with 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, tagline or contact_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 characters
  • website_url (optional) — saved on the new brand
A new brand can be refused when the account has reached its limit of business brands. The response says why. An invalid 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 when source_type is "document"; from rheos_list_brand_sources
  • provider (optional, for "ai_import") — claude, chatgpt, perplexity or gemini
  • brand_id (optional) — defaults to the organisation’s primary brand
  • max_chars, offset (optional) — when the response says truncated: true, pass its next_offset as offset to 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 markdown
  • source (optional): which assistant wrote it, in lower case. Defaults to claude. claude, chatgpt, perplexity and gemini each get their own slot; anything else shares one.
  • brand_id (optional): defaults to the organisation’s default business
  • brand_mode (optional): "personal" targets a personal brand, with user_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)
To bring the result back into Rheos, use 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. Pass brand_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.
An offering or audience 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 of tagline, mission, industry, sub_industry, website_url, country (two-letter code), founded_year, company_size (solo, 1-10, 11-50, 51-200, 201-1000 or 1000+), legal_entity, contact_email, phone_number and social_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 pass items.
  • description (optional) — one or two sentences
  • kind (optional) — "offering" (default) for a product or service, "differentiator" for a reason it stands out
  • status (optional) — planned, live or retired
  • items (optional) — several offerings in one call, up to 20, each with its own name, description, kind and status. Use it instead of name.
With 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’s id, or its exact name
  • name, description, kind, sortOrder (optional)
  • status (optional) — planned, live or retired

rheos_remove_offering

Delete an offering. This is permanent.
  • brand_id (required)
  • id (required) — the offering’s id, 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 pass items.
  • description (optional)
  • pains, desires (optional) — lists of short phrases
  • items (optional) — several audiences in one call, up to 20, each with its own name, description, pains and desires. Use it instead of name.
With 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’s id, or its exact name
  • name, 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’s id, or its exact name

rheos_unarchive_audience

Restore an archived audience to the active list.
  • brand_id (required)
  • id (required) — the audience’s id, 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 is rheos_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 from rheos_list_brands
  • palette (optional) — any of primary, secondary, accent, background and text, each a hex code (#RRGGBB or #RGB)
  • typography (optional) — heading_font and/or body_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 them
  • style_tags (optional) — the complete set of style chips; replaces the current set, and [] clears it. Only the Style tab’s own chips are accepted.
Pass at least one of these, or the call returns 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. 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 from rheos_list_brands
  • asset_id (required) — an image asset uploaded for this brand
  • slot (optional) — "logo" (default) adds it to the brand’s logos, "primary_logo" makes it the main logo, "icon" sets the small square site icon
SVG logos are not supported here, because 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 document
  • brand_id (optional): a business brand. Or pass account "personal" for your own personal brand. Leave both out to use the connection’s active brand.
Step 1, propose. Pass 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 are replace (old_string, new_string, optional replace_all), insert_before and insert_after (anchor, text), prepend and append (text), and replace_range (from, to, new_string). Every anchor must match the current text exactly once.
  • content: the complete new document, replacing the old one
Sending both is refused with 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. Each find must match the current text exactly once, unless you set replace_all: true.
  • markdown — the complete new document, replacing the old one
Also pass 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 from rheos_list_brands
  • limit (optional) — archived versions to return, default 10, max 50
  • include_markdown (optional) — true returns 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 from rheos_list_brands
  • version_id (required) — from rheos_list_brand_document_versions
  • base_version, base_hash (optional) — refuse the restore if the document changed since you read it
  • change_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 an asset_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 brand
  • post_copy (optional) — the post’s text, so the image is composed to fit it
  • count (optional) — 1 to 4 options, default 1
  • mode (optional) — gpt-image-2 (default), normal or pro. A pro image 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 session
  • iterate_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.
Every image it generates counts toward the account’s monthly image allowance, re-rolls included. Once the allowance is used up, the call returns a limit-reached error instead of an image. 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 previous rheos_generate_image call
  • name, 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) — from rheos_generate_image
  • limit (optional) — newest first, default 20, max 50
Each generation returns 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_url or image_base64 — use image_base64 only for a small image, about 100 KB or less
  • post_id (optional) — attach the image to an existing draft in the same call
  • alt_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_base64 or video_url — exactly one
  • alt_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 video
  • brand_id (required)
  • post_id (optional) — attach the asset to an existing draft in the same call
  • name, tags (optional)
  • metadata (optional) — provider, model, jobId, cost and prompt, 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_base64 or image_url
  • topic (required) — what the post should be about
  • channels (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)

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 searched
  • query (required) — a topic or idea, or exact words from the post
  • status (optional) — filter by post status; "published_or_partial" matches every post that went out
  • published_after, published_before (optional) — ISO dates
  • limit (optional) — default 10, max 50
Posts imported from a platform’s history keep only a title, so they are found by meaning only. Text matching reads the brand’s 500 most recent posts; 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 searched
  • limit (optional) — default 10, max 20
When nothing matches, the tool returns:
This is a real no-match result, not a fallback asset list. Broaden the query or generate an image instead of retrying the same query unchanged.

Reference

Small helpers split out so they don’t bloat rheos_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
Each capability returns 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.
Pages come back as markdown. Links to other sites are refused. For a Rheos account setting, 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.
The topics: 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.
Breaking change (19 Aug 2026): audiences entries were previously plain strings and are now objects (name plus optional detail). The source vocabulary also changed — it used to be "brand_pillars" | "org_pillars"; neither value is emitted any more.

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.
Breaking change (19 Aug 2026): themes entries were previously plain strings and are now objects (title plus optional detail). The source vocabulary also changed — it used to be "brand_pillars" | "org_pillars"; neither value is emitted any more.

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 characters
  • kind (required) — bug, wrong_result, missing_capability, confusing_description or slow
  • what_i_tried (required) — what the user asked for and the calls made
  • expected, actual (required) — what should have happened, and what did, including any error message
  • severity (required) — blocker, annoying or idea
  • tool (optional) — the name of the tool the report is about
  • brand_id (optional) — the brand involved
It is not for refusals that work as intended, such as a key without publishing access, a usage limit, a platform that is not connected or a delete the assistant held for the user to confirm. The assistant should tell the user how to fix those instead. It returns 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 error and may include hint, next_step, or tool-specific fields such as channels. When present, hint tells the caller which tool to invoke next (e.g. “Call rheos_list_brands first”).
  • All timestamps are ISO 8601 in UTC.
  • brand_id for personal brands is the user’s user_id; for business brands it’s the short id from rheos_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.
Last modified on November 19, 2026