watsi exposes the same capabilities through several doors. All of them read and write one workspace, the one your credential belongs to, and all of them come from the same contract: an action defined once is published as a REST route and as an MCP tool at the same time, with the same scopes.
| You want to… | Use | Credential |
|---|---|---|
| Have your backend read or write data (contacts, conversations, analytics) | REST API | API key wats_live_… |
| Let an AI assistant (Claude, ChatGPT, Cursor) query your workspace | MCP server | API key or OAuth 2.1 |
| Find out as soon as something happens (new message, booked appointment, handoff) | Webhooks | An HTTPS endpoint watsi registers |
| Put the agent’s chat on your website | Website widget | Configured in the app |
REST API
https://api.watsi.ai/v1/actions/<domain>/<verb>Every route is an action: GET to read (parameters go in the query string) and POST to write (JSON body). All of them authenticate with Authorization: Bearer <your key> and require one or more scopes. Responses are JSON; errors always look like { "error": { "code", "message" } }.
Your first call in five minutes.
AuthenticationKeys, scopes and limits.
PaginationHow each route pages.
ErrorsCodes, retries and idempotency.
Every route
This table is generated from the action contract when the site is built, so it cannot fall behind what the server mounts. The Idempotency-Key column marks the writes that accept that header (idempotency).
| Method | Path | Scopes | Idempotency-Key |
|---|---|---|---|
POST | /v1/actions/agents/assignment | agents:write | — |
GET | /v1/actions/agents/config | agents:read | — |
POST | /v1/actions/agents/create | agents:write | Yes |
POST | /v1/actions/agents/knowledge | knowledge:write | Yes |
POST | /v1/actions/agents/knowledge/delete | knowledge:write | Yes |
GET | /v1/actions/agents/list | agents:read | — |
POST | /v1/actions/agents/update | agents:write | Yes |
GET | /v1/actions/analytics/agent-performance | analytics:read | — |
GET | /v1/actions/analytics/escalations | analytics:read | — |
GET | /v1/actions/analytics/lead-attribution | analytics:read | — |
GET | /v1/actions/analytics/overview | analytics:read | — |
GET | /v1/actions/analytics/profiling-report | analytics:read | — |
POST | /v1/actions/attachments/create-upload | agents:write | Yes |
POST | /v1/actions/attachments/finalize | agents:write | Yes |
POST | /v1/actions/attachments/import-url | agents:write | Yes |
GET | /v1/actions/billing/credit-usage | billing:read | — |
GET | /v1/actions/billing/payment-history | billing:read | — |
GET | /v1/actions/billing/status | billing:read | — |
POST | /v1/actions/contacts/create | contacts:write | Yes |
GET | /v1/actions/contacts/list | contacts:read | — |
GET | /v1/actions/conversations/get | conversations:read | — |
GET | /v1/actions/conversations/list | conversations:read | — |
POST | /v1/actions/conversations/status | conversations:write | — |
POST | /v1/actions/crm/tags | crm:write | Yes |
POST | /v1/actions/crm/tags/remove | crm:write | Yes |
POST | /v1/actions/lifecycle/attach-file | lifecycle:write | Yes |
GET | /v1/actions/lifecycle/case-file | lifecycle:readbilling:read | — |
POST | /v1/actions/lifecycle/record-call | lifecycle:write | — |
POST | /v1/actions/lifecycle/step | lifecycle:write | — |
GET | /v1/actions/lifecycle/transcript | lifecycle:read | — |
GET | /v1/actions/messages/search | conversations:read | — |
GET | /v1/actions/resources/get | resources:read | — |
GET | /v1/actions/resources/list | resources:read | — |
POST | /v1/actions/scheduling/member-schedules | scheduling:write | — |
GET | /v1/actions/templates/search | templates:read | — |
GET | /v1/actions/voice/calls | agents:read | — |
GET | /v1/actions/voice/config | agents:read | — |
POST | /v1/actions/voice/config | agents:write | Yes |
GET | /v1/actions/voice/diagnose | agents:read | — |
GET | /v1/actions/workspace/integrations | integrations:read | — |
GET | /v1/actions/workspace/members | workspace:read | — |
GET | /v1/actions/workspace/settings | workspace:read | — |
The lifecycle/* routes serve watsi’s own customer-success process and require scopes only watsi issues. You don’t need them to integrate.
MCP server
https://mcp.watsi.ai/mcp speaks the Model Context Protocol over Streamable HTTP. Every MCP tool is one of the actions above, with the same scope; the MCP server has nothing the REST API lacks. Use it when the caller is a model rather than your code. MCP server guide.
Webhooks
watsi sends a POST to your HTTPS endpoint when an event happens: an inbound message, an assigned conversation, a booked appointment, an agent action. The watsi team registers endpoints for you. How they work · Event catalog.
Website widget
The agent’s chat on your site is installed with a snippet you copy from Integrations in the watsi app; it needs neither the API nor a key.