# Llamar a cualquier endpoint

> plazbot api: request autenticado a cualquier endpoint de la API de Plazbot, como stripe get o az rest

Fuente: https://developers.plazbot.com/cli/ia/api/

### Llamar a cualquier endpoint

Envía un request autenticado a cualquier endpoint de la API de Plazbot, aunque no tenga un comando propio en el CLI. Es el equivalente a `stripe get` o `az rest`: el CLI agrega el token, el workspace y la zona por ti, y siempre imprime la respuesta como JSON.

```bash
plazbot api <método> <ruta> [opciones]
```

El método es `get`, `post`, `put`, `patch` o `delete`. La ruta es solo el path (`/api/contact`); si no empieza con `/api/`, el CLI lo agrega. No se aceptan URLs completas: para cambiar de región usa `-z`.

### Parámetros

| Parámetro | Flag | Requerido | Descripción |
|-----------|------|-----------|-------------|
| Método | `<método>` | Sí | `get`, `post`, `put`, `patch` o `delete` |
| Ruta | `<ruta>` | Sí | Path del endpoint, ej. `/api/contact`. `{ws}` se reemplaza por el ID del workspace |
| Body | `-d, --data <json>` | No | Body JSON: en línea (`'{...}'`), desde un archivo (`@archivo.json`) o desde stdin (`-`) |
| Query | `-q, --query <key=value>` | No | Parámetro de query. Se puede repetir |
| Header | `-H, --header <key:value>` | No | Header adicional. Se puede repetir |
| Sin workspaceId | `--no-workspace-param` | No | No agrega `?workspaceId=<workspace>` a la query |
| Estado HTTP | `-i, --include` | No | Imprime el código HTTP en stderr |
| Workspace | `-w, --workspace <id>` | No | Workspace del request (por defecto, el activo) |
| Zona | `-z, --zone <zone>` | No | `LA` o `EU` (por defecto, la de la sesión) |
| Confirmar | `-y, --yes` | No | Omite la confirmación en métodos que no son GET |

### Qué agrega el CLI

- `Authorization: Bearer <token>` y `x-workspace-id` con el workspace de la sesión (o el de `-w`).
- `?workspaceId=<workspace>` en la query, salvo que ya lo pases con `-q` o uses `--no-workspace-param`.
- `{ws}` en la ruta, en los valores de `-q` y en el body se reemplaza por el ID del workspace.

### Confirmación y endpoints peligrosos

- **GET** se ejecuta directo.
- **POST, PUT, PATCH y DELETE** piden confirmación. Sin terminal interactiva (scripts, CI, agentes de IA) fallan con `confirmation_required` hasta que agregues `--yes`.
- Algunos endpoints **siempre** exigen `--yes`, aunque estés en una terminal, porque borran o envían en masa:

| Request | Qué hace |
|---------|----------|
| `POST /api/contact/delete-batch`, `delete-batch-dates`, `deleteMassive` | Borra contactos en masa |
| `DELETE /api/workspace/{id}` | Borra un workspace |
| `POST /api/workspace/{id}/integrations/deactivate-all` | Desactiva todos los canales |
| `POST /api/workspace/{id}/transfer-number` | Mueve un número a otro workspace |
| `POST /api/conversation/campaign` | Envía una campaña de WhatsApp (Meta la cobra) |
| `POST /api/ai-team/sql-query` | Ejecuta una consulta SQL |
| `DELETE /api/source/{id}/rows` | Borra todas las filas de una tabla |
| `DELETE /api/worker/logs/cleanup` | Borra los logs de los workers |
| `DELETE /api/user/{id}` | Borra un usuario |
| `DELETE /api/automation/Trash/{id}` | Borra una automatización de forma definitiva |

### Ejemplos

```bash
# Configuración del workspace (etiquetas, fases, pipelines, canales...)
plazbot api get /api/workspace/{ws}

# Miembros del equipo
plazbot api get /api/workspace/usersByWorkspaceId/{ws}

# Reporte de mensajes de una semana, en otro workspace de Europa
plazbot api get /api/report/message -q startDate=2026-10-01 -q endDate=2026-10-07 -w wok_AbcDef123 -z EU

# Crear una etiqueta (sin preguntar)
plazbot api post /api/workspace/{ws}/masterOfTags -d '{"name":"VIP","color":"#22c55e"}' --yes

# Body desde un archivo
plazbot api put /api/workspace/{ws}/view/viw_AbcDef123 -d @vista.json --yes

# Body desde stdin
cat cambios.json | plazbot api put /api/contact -q id=con_AbcDef123 -d - --yes

# Ver el código HTTP
plazbot api get /api/sequence -i
```

### Endpoints útiles de lectura

| Qué | Ruta (GET) |
|-----|------------|
| Configuración del workspace: etiquetas, fases, pipelines, variables, reglas, canales | `/api/workspace/{ws}` |
| Miembros del equipo | `/api/workspace/usersByWorkspaceId/{ws}` |
| Vistas guardadas | `/api/workspace/{ws}/view -q userId=usr_..` |
| Contactos no leídos | `/api/contact/unread-count -q currentUser=usr_..` |
| Log de envíos de plantillas | `/api/conversation` |
| Oportunidades | `/api/opportunity` (`-q pipelineId=..`, `-q contactId=..`) |
| Tareas | `/api/task -q pageNumber=1 -q pageSize=50` |
| Secuencias | `/api/sequence`, `/api/sequence/stats` |
| Automatizaciones | `/api/automation -q actives=true`, `/api/automation/{id}`, `/api/automation/logs -q automationId=..`, `/api/automation/contact/{contactId}/state` |
| Triggers de reglas | `/api/trigger -q isActive=true` |
| Webhooks de Developer | `/api/workspace/{ws}/webhooks`, `/api/workspace/{ws}/webhooks/deliveries` |
| Webhooks entrantes | `/api/workspace/{ws}/incoming-webhooks` |
| Base de conocimiento | `/api/knowledgeBase/{ws}` |
| Tablas de datos | `/api/source`, `/api/source/{id}/rows` |
| Llamadas | `/api/call` |
| Log de actividad | `/api/log -q eventType=..`, `/api/log/webhooks`, `/api/log/activities` |
| Versiones y logs de un agente IA | `/api/agent/versions -q agentId=..`, `/api/agent/logs -q agentId=..` |
| Workers | `/api/worker`, `/api/worker/metrics`, `/api/worker/{name}/logs` |
| Facturación (solo lectura) | `/api/billing`, `/api/billing/invoices` |

Para lo más común hay comandos propios con tabla y paginación: [`contacts`](https://developers.plazbot.com/cli/contacts/list), [`messages`](https://developers.plazbot.com/cli/messages/list), [`campaigns`](https://developers.plazbot.com/cli/campaigns/list), [`reports`](https://developers.plazbot.com/cli/reports) y el resto que lista [`plazbot commands`](https://developers.plazbot.com/cli/ia/commands).

### Resultado

La respuesta de la API se imprime tal cual en stdout, formateada como JSON. Si no es JSON (por ejemplo, la descarga de un archivo), se imprime como texto.

```json
{
"success": true,
"code": 200,
"errorCode": null,
"message": "List obtained successfully.",
"data": {
  "workspaceId": "wok_AbcDef123",
  "continuationToken": null,
  "data": []
}
}
```

Con `-i` el código HTTP sale en stderr (`HTTP 200 OK`), así no ensucia el JSON.

### Errores comunes

El comando termina con código `1` cuando la API responde HTTP 400 o más, o cuando la respuesta trae `"success": false` (muchos endpoints de Plazbot responden 200 aunque fallen). El body de la respuesta se imprime igual en stdout y el error va a stderr:

```json
{"error":{"message":"One or more validation errors occurred. currentUser: The currentUser field is required.","code":"request_failed","status":400}}
```

| Mensaje | Causa | Solución |
|---------|-------|----------|
| `This action needs confirmation and there is no interactive terminal.` | Método que no es GET sin terminal interactiva | Agrega `--yes` |
| `POST /api/... deletes contacts in bulk.` | Endpoint peligroso sin `--yes` | Revisa el request y repítelo con `--yes` |
| `Pass only the path, not a full URL.` | Pasaste `https://...` | Pasa solo la ruta y elige la región con `-z` |
| `The request body is not valid JSON.` | `-d` con JSON inválido | Revisa el JSON, o usa `-d @archivo.json` |
| `This session is read-only: it cannot change data.` | Sesión creada con `plazbot login --read-only` | Inicia sesión sin `--read-only` para hacer cambios |
| `Resource not found.` | Ruta o ID inexistente | Revisa la ruta y el workspace activo (`plazbot whoami`) |