API reference

The agent gateway, endpoint by endpoint

36 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.

The HTTP gateway below is live; the packaged toolkit is not. Every route, scope, and argument on these pages is generated from the gateway's own tool catalog and is accurate today. The wa CLI and wa-mcp server names are planned and not on npm yet, so treat those commands as the intended shape rather than something to copy — ask us for the current package name and key prefix if you want to wire an agent up now.

Base URL and authentication

The gateway is deployed per organization, so the host is yours; 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://your-server/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

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

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

usage:read

Read metered usage for the org