# Qué superficie usar

> Las cuatro formas de conectar tu sistema con watsi — API REST, servidor MCP, webhooks y el widget web — y cuándo conviene cada una.

Source: https://docs.watsi.ai/api/overview

watsi expone las mismas capacidades por varias puertas. Todas leen y escriben en **un solo espacio de trabajo**, el de la credencial con la que entras, y todas nacen del mismo contrato: una acción definida una vez se publica como ruta REST y como herramienta MCP a la vez, con los mismos alcances.

| Quieres…                                                                        | Usa                   | Credencial                        |
| ------------------------------------------------------------------------------- | --------------------- | --------------------------------- |
| Que tu backend lea o escriba datos (contactos, conversaciones, analíticas)      | [API REST](#api-rest) | Clave de API `wats_live_…`        |
| Que un asistente de IA (Claude, ChatGPT, Cursor) consulte tu espacio de trabajo | [Servidor MCP](/mcp)  | Clave de API u OAuth 2.1          |
| Enterarte en cuanto algo pasa (mensaje nuevo, cita agendada, escalamiento)      | [Webhooks](/webhooks) | Endpoint HTTPS que registra watsi |
| Poner el chat del agente en tu sitio web                                        | Widget web            | Se configura desde la app         |

## API REST

```http
https://api.watsi.ai/v1/actions/<dominio>/<verbo>
```

Cada ruta es una **acción**: `GET` para leer (los parámetros van en la query string) y `POST` para escribir (cuerpo JSON). Todas se autentican con `Authorization: Bearer <tu clave>` y exigen uno o más [alcances](/guides/authentication#alcances). Las respuestas son JSON; los errores siempre tienen la forma `{ "error": { "code", "message" } }`.

- [Inicio rápido](/quickstart)
    Tu primera llamada en cinco minutos.
- [Autenticación](/guides/authentication)
    Claves, alcances y límites.
- [Paginación](/guides/pagination)
    Cómo pagina cada ruta.
- [Errores](/error-handling)
    Códigos, reintentos e idempotencia.

### Todas las rutas

La tabla se genera del contrato de acciones al construir este sitio, así que no puede quedarse atrás de lo que el servidor monta. La columna **Idempotency-Key** marca las escrituras que aceptan ese encabezado ([idempotencia](/api/idempotency)).

| Método | Ruta | Alcances | Idempotency-Key |
| --- | --- | --- | --- |
| `POST` | `/v1/actions/agents/assignment` | `agents:write` | — |
| `GET` | `/v1/actions/agents/config` | `agents:read` | — |
| `POST` | `/v1/actions/agents/create` | `agents:write` | Sí |
| `POST` | `/v1/actions/agents/knowledge` | `knowledge:write` | Sí |
| `POST` | `/v1/actions/agents/knowledge/delete` | `knowledge:write` | Sí |
| `GET` | `/v1/actions/agents/list` | `agents:read` | — |
| `POST` | `/v1/actions/agents/update` | `agents:write` | Sí |
| `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` | Sí |
| `POST` | `/v1/actions/attachments/finalize` | `agents:write` | Sí |
| `POST` | `/v1/actions/attachments/import-url` | `agents:write` | Sí |
| `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` | Sí |
| `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` | Sí |
| `POST` | `/v1/actions/crm/tags/remove` | `crm:write` | Sí |
| `POST` | `/v1/actions/lifecycle/attach-file` | `lifecycle:write` | Sí |
| `GET` | `/v1/actions/lifecycle/case-file` | `lifecycle:read` + `billing: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` | Sí |
| `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` | — |

> **Note**

Las rutas `lifecycle/*` sirven al proceso de acompañamiento de clientes de watsi y exigen alcances que sólo emite watsi. No las necesitas para integrarte.

## Servidor MCP

`https://mcp.watsi.ai/mcp` habla el Model Context Protocol por Streamable HTTP. Cada herramienta MCP es una de las acciones de arriba, con el mismo alcance; el servidor MCP no tiene nada que la API REST no tenga. Úsalo cuando quien llama es un modelo y no tu código. [Guía del servidor MCP](/mcp).

## Webhooks

watsi hace `POST` a tu endpoint HTTPS cuando ocurre un evento: un mensaje entrante, una conversación asignada, una cita agendada, una acción del agente. Los endpoints los registra el equipo de watsi por ti. [Cómo funcionan](/webhooks) · [Catálogo de eventos](/webhooks/events).

## Widget web

El chat del agente en tu sitio se instala con un fragmento de código que copias desde **Integraciones** en la app de watsi; no necesita la API ni una clave.