API reference

Every agent surface — the MCP server, the CLI, and the typed client — is a skin over a single contract: the /api/agent gateway. Each tool below is exactly one gateway call.

Authentication

Send your scoped key as the agent credential. The MCP server and CLI read it from RCS_AGENT_KEY; the typed client takes it as apiKey. The base URL is your gateway (RCS_GATEWAY_URL).

RCS_GATEWAY_URL=https://your-server
RCS_AGENT_KEY=rcsk_live_…

Tools

Grouped by domain. Every entry below is generated from the gateway’s own tool catalog by scripts/generate-agent-catalog.mjs — re-run it when the gateway ships new tools rather than editing between the markers.

Discovery

capabilities

• HTTP: GET /capabilities
• CLI: rcs capabilities
• Scope: any key
• Describe the gateway: tool catalog, the scopes this key holds, and pricing posture. Call first to plan what you may do.

Templates

search_templates

• HTTP: GET /templates

• CLI: rcs search [query] [--channel RCS] [--category KEY]

• Scope: templates:read

• Search the published RCS template marketplace. Returns normalized listings (id, name, rating, cloneCount, categoryKeys).

  Argument	Type	Required
  q	string
  category	string
  channel	string
  sort	string
  page	number
  pageSize	number

get_template

• HTTP: GET /templates/:id

• CLI: rcs get <id>

• Scope: templates:read

• Fetch one template by id (a published marketplace listing or one your org owns).

  Argument	Type	Required
  id	string	yes

render_template

• HTTP: POST /templates/:id/render

• CLI: rcs render <id> [--var key=value ...]

• Scope: templates:read

• Validate a template and return the rendered RCS payload + variable-bound SMS/MMS fallback, without sending. Use to inspect before cloning/sending.

  Argument	Type	Required
  id	string	yes
  variables	object

create_template

• HTTP: POST /templates

• CLI: rcs create --file <template.json>

• Scope: templates:write

• Create a template draft in your org. Compose a TemplateContent (text/card/carousel) with a REQUIRED non-empty smsFallback; the shared RCS validator gates it. Submit it (submit_template) and await provider approval before send_message for rich RCS; an unsubmitted template delivers as SMS fallback.

  Argument	Type	Required
  name	string	yes
  description	string
  channel	string
  category	string
  content	object	yes
  tags	array

update_template

• HTTP: PUT /templates/:id

• CLI: no CLI verb yet — HTTP or MCP

• Scope: templates:write

• Partially update a template your org owns: name, description, category, tags, knowledgeDoc, and content (re-validated by the shared RCS validator — a non-empty smsFallback is still required). Only the fields you pass change. Editing the CONTENT of an already-approved template invalidates that approval: submit_template it again and await approval, or it delivers as SMS fallback until then. Use get_template first to edit incrementally rather than overwriting blind.

  Argument	Type	Required
  id	string	yes
  name	string
  description	string
  channel	string
  category	string
  content	object
  tags	array
  knowledgeDoc	string

duplicate_template

• HTTP: POST /templates/:id/duplicate

• CLI: no CLI verb yet — HTTP or MCP

• Scope: templates:write

• Duplicate a template your org OWNS into a fresh private draft (e.g. to iterate a variant without touching the original). The copy keeps the content, channel, category, tags and knowledge base, but starts unsubmitted — it has no provider approval of its own until you submit_template it. For copying someone else’s PUBLISHED marketplace listing, use clone_template instead.

  Argument	Type	Required
  id	string	yes

delete_template

• HTTP: DELETE /templates/:id

• CLI: no CLI verb yet — HTTP or MCP

• Scope: templates:write

• Delete a template your org owns. IRREVERSIBLE, and it also removes the template from the provider (Twilio), so an approved template loses its approval and can no longer be sent. Broadcasts that already went out are unaffected. Prefer this only for drafts and abandoned iterations; ask the user before deleting anything they have submitted or sent.

  Argument	Type	Required
  id	string	yes

clone_template

• HTTP: POST /marketplace/:id/clone

• CLI: rcs clone <id>

• Scope: marketplace:clone

• Clone a published marketplace template into your org as a fresh private draft. Returns the new template. To deliver rich RCS rather than SMS fallback, submit_template it and await provider approval before send_message.

  Argument	Type	Required
  id	string	yes

submit_template

• HTTP: POST /templates/:id/submit

• CLI: rcs submit <id>

• Scope: templates:submit

• Submit an org-owned template to the provider (Twilio) for approval. Returns the contentSid + approval status.

  Argument	Type	Required
  id	string	yes

send_message

• HTTP: POST /messages/send

• CLI: rcs send <blueprintId> --to +1555... [--var key=value ...]

• Scope: messages:send

• Send an org-owned template to a list of E.164 phone numbers (RCS-first with mandatory SMS/MMS fallback). Pass the template’s blueprintId or id. The template sends as rich RCS only after submit_template + provider approval; until then it delivers as SMS fallback — the returned funnel’s fellBackToSms count signals how many recipients got SMS instead of RCS. Bills your org. Returns the send funnel.

  Argument	Type	Required
  blueprintId	string	yes
  to	array	yes
  variables	object
  name	string

Surveys

search_surveys

• HTTP: GET /surveys

• CLI: rcs surveys [query] [--status ACTIVE]

• Scope: surveys:read

• List/search the surveys your org owns. Returns each survey with its recipients + responses counts.

  Argument	Type	Required
  q	string
  status	string
  page	number
  pageSize	number

get_survey

• HTTP: GET /surveys/:id

• CLI: rcs survey get <id>

• Scope: surveys:read

• Fetch one survey your org owns by id (its full definition).

  Argument	Type	Required
  id	string	yes

render_survey

• HTTP: POST /surveys/:id/render

• CLI: no CLI verb yet — HTTP or MCP

• Scope: surveys:read

• Preview a survey the way a respondent sees it: the text body + RCS chip titles for each question. Side-effect-free.

  Argument	Type	Required
  id	string	yes

create_survey

• HTTP: POST /surveys

• CLI: rcs survey create --file <survey.json>

• Scope: surveys:write

• Create a survey draft in your org. Provide a SurveyDefinition (intro? + questions[] of type rating/single_select/text/comment); the shared validator gates it. PICTURES: every question should carry an imageUrl, and the definition should carry headerImageUrl (start picture) and outroImageUrl (finish picture). If the user provided no pictures, WEB-SEARCH for suitable, relevant images first and pass their https URLs — the server automatically re-hosts every image onto the platform GCS bucket, so external URLs are safe to pass and never hotlinked.

  Argument	Type	Required
  name	string	yes
  description	string
  definition	object	yes
  startDate	string
  endDate	string
  timezone	string
  languageCode	array
  isPreferencesSurvey	boolean
  channel	string

clone_survey

• HTTP: POST /surveys/:id/clone

• CLI: no CLI verb yet — HTTP or MCP

• Scope: marketplace:clone

• Duplicate an org-owned survey into a fresh DRAFT (e.g. to iterate a variant). Returns the new survey.

  Argument	Type	Required
  id	string	yes

delete_survey

• HTTP: DELETE /surveys/:id

• CLI: no CLI verb yet — HTTP or MCP

• Scope: surveys:write

• Delete a survey your org owns. IRREVERSIBLE: its responses and sessions are deleted with it, so any results you have not already read are lost. Ask the user before deleting a survey that has been sent or has responses — read get_results first if in doubt.

  Argument	Type	Required
  id	string	yes

submit_survey

• HTTP: POST /surveys/:id/submit

• CLI: rcs survey submit <id>

• Scope: surveys:submit

• Submit a survey for provider approval: on RCS its button-question templates, on WhatsApp its single Flow template. Returns the survey with the resulting approval state.

  Argument	Type	Required
  id	string	yes
  channel	string

send_survey

• HTTP: POST /surveys/:id/send

• CLI: rcs survey send <id> [--to +1555...] [--audience <id>]

• Scope: surveys:send

• Send a survey to explicit E.164 numbers (the CRM-triggered single-customer send) and/or saved audiences. Flips the survey ACTIVE. Bills your org. Returns { recipients, sent }.

  Argument	Type	Required
  id	string	yes
  to	array
  audienceIds	array
  channel	string

update_survey

• HTTP: PATCH /surveys/:id

• CLI: rcs survey update <id> --file <patch.json>

• Scope: surveys:write

• Partially update a survey: name, description, definition (re-validated; editing a submitted WhatsApp survey requires resubmission), startDate/endDate, and audienceIds — setting audienceIds on a future-dated survey schedules the send to fire automatically at startDate. PICTURES: as with create_survey, keep every question’s imageUrl plus headerImageUrl/outroImageUrl populated — web-search for images when none were provided; the server re-hosts all image URLs onto GCS.

  Argument	Type	Required
  id	string	yes
  name	string
  description	string
  definition	object
  status	string
  startDate	string
  endDate	string
  audienceIds	array
  channel	string

list_survey_sends

• HTTP: GET /surveys/:id/sends

• CLI: rcs survey sends <id>

• Scope: surveys:read

• A survey’s outbound send log (live + test sends), newest first, with per-message delivery status — including failed/stubbed attempts and the reason they did not deliver.

  Argument	Type	Required
  id	string	yes

send_survey_test

• HTTP: POST /surveys/:id/send-test

• CLI: rcs survey send-test <id> --to +1555...

• Scope: surveys:send

• Send a one-off TEST of the survey to a single E.164 number (does not change status or audiences). Check list_survey_sends afterwards for the delivery outcome.

  Argument	Type	Required
  id	string	yes
  number	string	yes
  channel	string

get_results

• HTTP: GET /surveys/:id/results

• CLI: rcs survey results <id>

• Scope: results:read

• Read a survey’s aggregated results: per-question option counts / rating averages / text samples + completion totals (multi-part questions aggregate per part; free-text answers are auto-translated to English).

  Argument	Type	Required
  id	string	yes

upload_media

• HTTP: POST /media/upload

• CLI: rcs upload-image (--file <image.png> | --from-url <url>)

• Scope: surveys:write

• Store one picture on the platform GCS bucket and get its stable https URL — the only kind of URL survey/template media should use. Pass EITHER the image inline (base64 + mime) OR an https sourceUrl the server fetches and re-hosts (use this for web-searched pictures).

  Argument	Type	Required
  base64	string
  mime	string
  filename	string
  sourceUrl	string

Grounding knowledge

get_knowledge

• HTTP: GET /templates/:id/knowledge

• CLI: rcs knowledge <id> --get

• Scope: templates:read

• Read a template’s knowledge base: the grounding document text plus whether answering is enabled. Use before set_knowledge to edit a doc incrementally instead of overwriting it blind.

  Argument	Type	Required
  id	string	yes

set_knowledge

• HTTP: PUT /templates/:id/knowledge

• CLI: rcs knowledge <id> --set-file <doc.md>

• Scope: templates:write

• Set/replace a template’s knowledge base: the grounding document AI answers are generated from when recipients reply. Include operating instructions in the doc itself — e.g. “Any question not answered by this document must be answered exactly: …”. Setting a doc re-enables answering.

  Argument	Type	Required
  id	string	yes
  doc	string	yes

delete_knowledge

• HTTP: DELETE /templates/:id/knowledge

• CLI: rcs knowledge <id> --delete

• Scope: templates:write

• Delete a template’s knowledge base document.

  Argument	Type	Required
  id	string	yes

enable_knowledge

• HTTP: POST /templates/:id/knowledge/enable

• CLI: rcs knowledge <id> --enable

• Scope: templates:write

• Enable knowledge answering on a template (the doc is used again).

  Argument	Type	Required
  id	string	yes

disable_knowledge

• HTTP: POST /templates/:id/knowledge/disable

• CLI: rcs knowledge <id> --disable

• Scope: templates:write

• Disable knowledge answering on a template WITHOUT deleting the doc (pause).

  Argument	Type	Required
  id	string	yes

Audiences

search_audiences

• HTTP: GET /audiences

• CLI: no CLI verb yet — HTTP or MCP

• Scope: audiences:read

• List/search the audiences (saved contact lists) your org owns. Returns each audience with its name, source, and contactCount.

  Argument	Type	Required
  q	string
  page	number
  pageSize	number

get_audience

• HTTP: GET /audiences/:id

• CLI: no CLI verb yet — HTTP or MCP

• Scope: audiences:read

• Fetch one audience your org owns by id.

  Argument	Type	Required
  id	string	yes

list_audience_contacts

• HTTP: GET /audiences/:id/contacts

• CLI: no CLI verb yet — HTTP or MCP

• Scope: audiences:read

• Paginated list of an audience’s contacts. Use q to find someone in a large imported batch instead of paging through it — it matches on the server, over the whole audience, so it keeps working on lists too big to page.

  Argument	Type	Required
  id	string	yes
  q	string
  page	number
  pageSize	number

create_audience

• HTTP: POST /audiences

• CLI: no CLI verb yet — HTTP or MCP

• Scope: audiences:write

• Create a saved audience (contact list) in your org, optionally seeded with contacts (e.g. leads parsed from a CSV). Every contact needs a reachable E.164-ish number — a contact with no valid number fails the whole create with a 400 (fix the row rather than silently dropping it). Use attributes for any extra CSV columns you want available as {{key}} merge fields later.

  Argument	Type	Required
  name	string	yes
  description	string
  source	string
  contacts	array

import_contacts

• HTTP: POST /audiences/:id/contacts

• CLI: no CLI verb yet — HTTP or MCP

• Scope: audiences:write

• Append contacts to an existing audience (e.g. more leads from a later CSV batch). Same reachability rule as create_audience: every contact needs a valid number or the whole import 400s.

  Argument	Type	Required
  id	string	yes
  contacts	array	yes

delete_audience

• HTTP: DELETE /audiences/:id

• CLI: no CLI verb yet — HTTP or MCP

• Scope: audiences:write

• Delete an audience and all of its contacts (org-scoped, irreversible).

  Argument	Type	Required
  id	string	yes

Account

get_usage

• HTTP: GET /usage
• CLI: rcs usage
• Scope: usage:read
• Read your org’s month-to-date metered message usage.

Guarantees

• Scoped — a call fails unless your key holds the tool’s scope.
• Validated — authored/rendered templates run through the shared channel validator.
• Gated — send_message clears the same provider-approval gate as a human send.
• Safe sends — destinations are validated as E.164; the gateway is rate-limited.
• Metered — get_usage reads the same ledger that billing counts.