The Claude Agent · Connect
REST API and webhooks
Drive agents from your own code.
Pro
Everything you do with agents in the app can be done from your own code: a WordPress screen, an n8n flow, a Slack bot. This page is the overview; every route, field and response is in the Claude Agent API reference.
Before you start
- The REST API runs on the machine SocialMate runs on, at
http://localhost:3456/v1by default. Creating your first key switches it on; the Tunnel tab under API & Integrations shows the API server and holds the tunnel for reaching it from elsewhere. - Create a key under API & Integrations → API Keys and send it as the
x-api-keyheader. Reads needreadscope (the global/v1/ai/settingsand/v1/ai/sensesneed anadminkey for all accounts),POST …/eventsneedssend, every other write needsadmin. - Every agent route is Pro. On Free each one answers
402.
The routes
-
List agents with today’s numbers; read one agent’s full configuration.
GET /v1/agentsGET /v1/agents/{id} -
Give a number its agent from a preset (it starts as a draft).
POST /v1/accounts/{id}/agent -
Change settings (version-checked) or remove the agent.
PATCH /v1/agents/{id}DELETE /v1/agents/{id} -
Pause or switch on one agent.
POST /v1/agents/{id}/pause…/resume -
The global kill switch and the monthly cap for all agents.
GET/PUT /v1/ai/settings -
Runs, tokens and cost per agent, or for all agents.
GET /v1/agents/{id}/usageGET /v1/usage/summary -
What the agent decided in each turn, with every step.
GET /v1/agents/{id}/runs…/runs/{runId} -
Actions waiting for approval; approve or reject one.
GET /v1/agents/{id}/approvalsPOST …/approvals/{aid} -
Who needs a person, the chats the agent worked in, a chat’s messages.
GET /v1/agents/{id}/handoffs…/conversations…/chats/{chatId}/messages -
Take a chat over, hand it back, or answer as a person.
POST …/{id}/chats/{chatId}/takeover…/release…/reply -
Start an event job: the agent writes the person on your event.
POST /v1/agents/{id}/events -
Read, add and remove knowledge entries.
GET/POST /v1/agents/{id}/knowledgeDELETE …/knowledge/{kid} -
Read or add facts the agent keeps about one customer.
GET/POST /v1/agents/{id}/memory/{chatId} -
Voice notes, photos, voice replies and web search.
GET/PUT /v1/ai/sensesPOST /v1/ai/senses/test -
Used by the WordPress plugin to pair, verify and unpair.
/v1/connectors/wordpress…
Three examples
Find your agents and what waits for you
curl http://localhost:3456/v1/agents \
-H "x-api-key: YOUR_KEY"
Each agent comes with its id, status, autonomy, model, today’s numbers and the count of open hand-offs and pending approvals.
Approve a held action
curl -X POST http://localhost:3456/v1/agents/AGENT_ID/approvals/APPROVAL_ID \
-H "x-api-key: ADMIN_KEY" -H "Content-Type: application/json" \
-d '{ "decision": "approve", "decidedBy": "[email protected]" }'
Tell the agent an order shipped
curl -X POST http://localhost:3456/v1/agents/AGENT_ID/events \
-H "x-api-key: YOUR_KEY" -H "Content-Type: application/json" \
-d '{
"type": "order.shipped",
"idempotencyKey": "wc-order-1042-shipped",
"recipient": { "phone": "+1 555 123 0001", "name": "Jane" },
"data": { "orderNumber": "1042", "courier": "DHL" }
}'
202 means queued. The agent needs an event job for that type switched on (here Order updates); consent, the frequency cap and retries are explained in Jobs and event jobs.
Webhooks
Subscribe to these under API & Integrations → Webhooks to mirror the agent in your own tools. Payloads are in Agent events.
agent.reply_sent— the agent replied in a chat (messages sent, the run’s cost)agent.draft_created— a draft reply waits for a person (Observe mode)agent.approval_requested— an action is waiting for approvalagent.approval_decided— an approval was approved or rejected, and by whomagent.handoff_requested— a chat was handed to a person, with the reasonagent.handoff_resolved— a chat was handed back to the agentagent.paused— an agent (or, from the kill switch, every agent) was pausedagent.resumed— an agent was resumedagent.budget_warning— an agent reached 80% of its monthly budget, or a cap was reached and the fallback model could not take overagent.injection_detected— a prompt-injection attempt was detectedagent.job_failed— an event job could not runagent.lead_captured— the agent saved a lead’s details on the contact
n8n and MCP
No code needed: the SocialMate n8n node has an Agent resource and the agent trigger events (n8n docs), and the open-source socialmate-mcp server exposes the agent to Claude Desktop, Cursor or any MCP client through its whatsapp_agent_* tools (MCP server docs).