API reference

The agent gateway, endpoint by endpoint

48 calls over one authenticated HTTP surface. Every route is listed with its method, path, and the scope it requires — the same catalog the MCP server and CLI are built from.

Base URL and authentication

The gateway is hosted for you — every org calls the same base URL, and every path below is relative to /api/agent. Authenticate with a scoped agent key as a bearer token. Agent keys are a separate rail from the human app — the master key is not honoured here, and an agent key cannot reach human admin routes.

export WA_AGENT_KEY=<your agent key>

curl "https://rcs-templates-api-dot-msg2ai-server.ue.r.appspot.com/api/agent/capabilities" \
  -H "Authorization: Bearer $WA_AGENT_KEY"

Keys are minted by an org admin, shown once, stored only as a SHA-256 hash, and revocable. Revocation fails closed.

Prefer tools over HTTP? The same catalog is exposed as an MCP server and a CLI.

OpenAPI document

Every route on this page is also published as OpenAPI 3.1, generated from the gateway's own tool catalog — so paths, scopes, and request arguments are the schemas it actually validates against, not a restatement. Responses are described loosely: the catalog types inputs but not outputs yet.

/openapi.json

Reference

Discovery

1 call

One call that describes the rest. Ask the gateway what it can do and which of those things your key is allowed to do, then plan from the answer instead of from documentation that may be older than the deployment.

Reference

Templates

10 calls

Author, clone, render, approve, and send message templates. This is the core loop: find or write a template, render it to check the payload and its SMS fallback, submit it for provider approval, then broadcast it.

Reference

Surveys

13 calls

Conversational surveys are multi-turn templates: a question set with branching, sent to an audience, with answers that come back as structured data. They go through the same approval gate as templates.

Reference

Grounding knowledge

5 calls

A template can carry a grounding document — the source of truth a reply bot answers from. These calls attach it, read it, remove it, and switch it on or off without deleting it.

Reference

Audiences

6 calls

Named contact lists to send against. Import E.164 contacts once, then reference the audience instead of passing recipient arrays around.

Reference

Contacts

3 calls

The org-level record of a person — one per number, shared across every audience they appear in. Read their consent, opt-out, merge fields and tags, and correct the details that are yours to correct. Consent itself is readable here and deliberately not writable: recording or clearing it is compliance-sensitive and belongs to a human.

Reference

Inbox

4 calls

Threads, one per phone number, and replying into them. An agent can triage the whole inbox read-only; replying is the one call here that reaches a real phone, bills the org, and honours every gate a human composer hits — opt-out, allowance, and the WhatsApp 24-hour window.

Reference

Webhooks

5 calls

Outbound event subscriptions: register an HTTPS endpoint and the platform posts signed events to it as messages are delivered, replies arrive, and campaigns finish. The signing secret is shown exactly once, when the endpoint is created.

Reference

Account

1 call

Read-only view of the org's metered usage — the same ledger the human dashboard and the billing meter count.

Reference

All routes at a glance

Method	Path	Tool	Scope
GET	/capabilities	capabilities	any key
GET	/templates	search_templates	templates:read
GET	/templates/:id	get_template	templates:read
POST	/templates/:id/render	render_template	templates:read
POST	/templates	create_template	templates:write
PUT	/templates/:id	update_template	templates:write
POST	/templates/:id/duplicate	duplicate_template	templates:write
DELETE	/templates/:id	delete_template	templates:write
POST	/marketplace/:id/clone	clone_template	marketplace:clone
POST	/templates/:id/submit	submit_template	templates:submit
POST	/messages/send	send_message	messages:send
GET	/surveys	search_surveys	surveys:read
GET	/surveys/:id	get_survey	surveys:read
POST	/surveys/:id/render	render_survey	surveys:read
POST	/surveys	create_survey	surveys:write
POST	/surveys/:id/clone	clone_survey	marketplace:clone
DELETE	/surveys/:id	delete_survey	surveys:write
POST	/surveys/:id/submit	submit_survey	surveys:submit
POST	/surveys/:id/send	send_survey	surveys:send
PATCH	/surveys/:id	update_survey	surveys:write
GET	/surveys/:id/sends	list_survey_sends	surveys:read
POST	/surveys/:id/send-test	send_survey_test	surveys:send
GET	/surveys/:id/results	get_results	results:read
POST	/media/upload	upload_media	surveys:write
GET	/templates/:id/knowledge	get_knowledge	templates:read
PUT	/templates/:id/knowledge	set_knowledge	templates:write
DELETE	/templates/:id/knowledge	delete_knowledge	templates:write
POST	/templates/:id/knowledge/enable	enable_knowledge	templates:write
POST	/templates/:id/knowledge/disable	disable_knowledge	templates:write
GET	/usage	get_usage	usage:read
GET	/audiences	search_audiences	audiences:read
GET	/audiences/:id	get_audience	audiences:read
GET	/audiences/:id/contacts	list_audience_contacts	audiences:read
POST	/audiences	create_audience	audiences:write
POST	/audiences/:id/contacts	import_contacts	audiences:write
DELETE	/audiences/:id	delete_audience	audiences:write
GET	/conversations	list_conversations	conversations:read
GET	/conversations/:id	get_conversation	conversations:read
POST	/conversations/:id/reply	reply	conversations:write
POST	/conversations/:id/assign	assign_conversation	conversations:write
GET	/webhooks	list_webhooks	webhooks:manage
POST	/webhooks	create_webhook	webhooks:manage
PUT	/webhooks/:id	update_webhook	webhooks:manage
DELETE	/webhooks/:id	delete_webhook	webhooks:manage
POST	/webhooks/:id/test	test_webhook	webhooks:manage
GET	/contacts	list_contacts	contacts:read
GET	/contacts/:id	get_contact	contacts:read
PATCH	/contacts/:id	update_contact	contacts:write

Scopes

An agent key is a capability token: it carries exactly the scopes it was minted with and nothing more. A call outside a key's scopes is rejected before it reaches the handler.

templates:read

Search, fetch, and render templates, and read grounding docs

templates:write

Author, revise, duplicate, and delete drafts, and manage grounding

templates:submit

Submit drafts for provider approval

marketplace:clone

Clone marketplace templates and surveys into your org

messages:send

Broadcast templates to recipients

surveys:read

Search, fetch, render, and list sends for surveys

surveys:write

Author, patch, and delete surveys, and upload media

surveys:submit

Submit surveys for provider approval

surveys:send

Send survey tests and live survey runs

results:read

Read survey responses

audiences:read

List audiences and their contacts

audiences:write

Create and delete audiences, and import contacts

conversations:read

List threads, and read a thread with its messages

conversations:write

Reply into a thread, and assign or release it

webhooks:manage

contacts:read

Search and read the org-level contact record

contacts:write

Correct names, email, merge fields and tags — never consent

usage:read

Read metered usage for the org