# API (/es/docs/developer/api)
Sift ofrece una API REST en `https://api.getsift.ai`. Úsala para leer acciones, agentes, colas, conversaciones y analíticas. También puedes establecer campos personalizados, enviar casos de moderación e ingerir registros normalizados.
## De un vistazo [#de-un-vistazo]
| | |
| --- | --- |
| API REST en `https://api.getsift.ai` | ✅ |
| Leer acciones, agentes, colas, analíticas; buscar conversaciones | ✅ |
| Escritura: campos personalizados, ingesta de moderación, ingesta normalizada | ✅ |
| Enviar una respuesta como mensaje dirigido al cliente | ❌ no disponible en esta API hoy |
| Autenticación con encabezado `X-API-Key` | ✅ |
| Especificación OpenAPI y Swagger UI | ✅ |
| DSL de operaciones completo en `GET /v0/action/list?fullFilter=` | ✅ |
| Límite de tasa por clave | ❌ aún no implementado |
| Versión actual `v0` | ✅ |
{/* screenshot */}
Explora los endpoints de la API REST en el Swagger UI interactivo.
## Autenticación [#autenticación]
Cada solicitud debe incluir tu clave de API en el encabezado `X-API-Key`:
```http
GET /v0/action/list
X-API-Key: sk_live_your_key_here
```
Consulta la página de [Claves de API](/docs/developer/api-keys) para saber cómo generar y administrar claves, y qué puede y no puede hacer una clave.
## Explorar la API [#explorar-la-api]
Sift publica una especificación OpenAPI completa y un Swagger UI interactivo:
* **OpenAPI JSON**: `https://api.getsift.ai/docs/json`
* **Swagger UI**: `https://api.getsift.ai/docs`
Puedes importar la especificación OpenAPI en Postman, Insomnia o cualquier cliente de API.
## Primera solicitud para un agente [#primera-solicitud-para-un-agente]
Lee la [referencia de campos de la API](/docs/developer/api-reference) antes de construir una solicitud.
Usa el [OpenAPI JSON](https://api.getsift.ai/docs/json) para obtener esquemas completos legibles por máquina.
```sh
curl --get 'https://api.getsift.ai/v0/action/list' \
--header "X-API-Key: $SIFT_API_KEY" \
--data-urlencode 'fullFilter=src=TWITTER+st=OPEN' \
--data-urlencode 'from=2026-10-01T00:00:00Z' \
--data-urlencode 'to=2026-10-07T23:59:59Z' \
--data-urlencode 'pageSize=20'
```
`SIFT_API_KEY` es una variable de entorno, no una clave literal en el ejemplo.
`fullFilter` aplica todas las condiciones y no agrega ningún valor predeterminado de respondido.
Los parámetros heredados `filter` y `filterJson` leen solo el indicador de respondido. No los uses para filtrar por plataforma o cola.
Inspecciona el arreglo `data` de este endpoint. Otros endpoints REST usan sus propios envoltorios de respuesta.
Para recorridos de cursor confiables y llamadas de agente dependientes, usa [MCP](/docs/developer/mcp).
## Endpoints [#endpoints]
| Método | Ruta | Descripción |
|--------|------|-------------|
| `GET` | `/v0/action/list` | Lista acciones. Admite `fullFilter`, rango de fechas y orden; consulta [Sintaxis de consulta](/docs/developer/query-syntax) |
| `GET` | `/v0/action/:id` | Obtiene una sola acción |
| `GET` | `/v0/actions/:actionId/custom-fields` | Lee los campos personalizados de una acción (requiere clave con alcance `read`) |
| `PATCH` | `/v0/actions/:actionId/custom-fields` | Establece los campos personalizados de una acción (requiere clave con alcance `write`) |
| `GET` | `/v0/agents` | Lista agentes con métricas de rendimiento |
| `GET` | `/v0/agents/:id` | Obtiene un solo agente |
| `GET` | `/v0/queues` | Lista colas con métricas |
| `GET` | `/v0/analytics/tags` | Estadísticas del panel de etiquetas |
| `GET` | `/v0/analytics/tags/volume` | Volumen de etiquetas a lo largo del tiempo |
| `GET` | `/v0/analytics/sentiment` | Distribución diaria de sentimiento |
| `GET` | `/v0/analytics/sentiment/by-tag` | Sentimiento desglosado por etiqueta |
| `GET` | `/v0/analytics/engagement` | Percentiles de participación, crecimiento semanal y datos de embudo |
| `GET` | `/v0/conversations/search` | Búsqueda de texto completo y DSL en conversaciones |
| `POST` | `/v0/moderation/cases` | Envía un caso de moderación (requiere `write`) |
| `POST` | `/v0/moderation/cases/batch` | Envía entre 1 y 100 casos de moderación en orden (requiere `write`) |
| `GET` | `/v0/moderation/cases/:caseId` | Consulta el estado de evaluación actual exacto (requiere `read`) |
| `POST` | `/v0/ingest/records` | Ingesta entre 1 y 500 registros normalizados de forma asíncrona (requiere `write`) |
No existe ningún endpoint que envíe o publique una respuesta en nombre de un cliente; las rutas de escritura cubren campos personalizados, envíos de moderación, ingesta normalizada y Custom API.
### Ingesta de moderación [#ingesta-de-moderación]
Los endpoints de moderación están disponibles solo cuando tu organización está configurada para el modo de moderación `ad_policy` de Sift. La ingesta valida la solicitud completa antes de encolar el trabajo en el pipeline normal de ingesta y síntesis de Sift.
El `externalId` es inmutable dentro de tu organización. Reintentar exactamente el mismo envío devuelve `duplicate`. Reutilizar un `externalId` existente con contenido conocido diferente devuelve `409` para el endpoint de caso único. En lote, cada entrada recibe un resultado ordenado de `accepted`, `duplicate` o `rejected`; un elemento en conflicto se rechaza sin impedir que otros elementos válidos sean aceptados.
Usa el `caseId` devuelto con el endpoint GET. La consulta devuelve solo la evaluación del flujo de trabajo de política activo actualmente y nunca recurre a una evaluación completada anterior. Un caso puede reportar `policy_not_configured`, `pending`, `running`, `completed` o `failed`. La decisión final se incluye solo después de la finalización.
## Importación por Custom API [#importación-por-custom-api]
Usa [Custom API](/docs/integrations/custom-api) para importar contenido desde tus herramientas. Crea una fuente en Integrations y una clave Import para las fuentes seleccionadas. La importación requiere `ingest`; leer recibos requiere `ingest:read`. Las claves Reporting y Write no otorgan estos alcances.
La guía incluye importaciones individuales y por lotes, validación, recibos, hilos y correcciones.
## Formato de error [#formato-de-error]
Los errores devuelven un cuerpo JSON consistente:
```json
{
"success": false,
"error": "Action not found"
}
```
Algunos endpoints agregan campos adicionales en casos de error específicos; por ejemplo, el `PATCH` de campos personalizados devuelve un objeto `fieldErrors` (nombre de campo → mensaje) en un `422`. Un error de servidor no capturado siempre devuelve `500` con `{ "success": false, "error": "Internal server error" }`.
Códigos de estado comunes: `400` (solicitud incorrecta), `401` (clave faltante o inválida), `403` (prohibido, por ejemplo una clave con alcance `read` llamando a una ruta de escritura), `404` (no encontrado), `409` (conflicto de identificador inmutable), `422` (validación fallida), `500` (error del servidor).
## Versiones [#versiones]
La versión actual de la API es `v0`. Los cambios que rompen compatibilidad se introducirán bajo un nuevo prefijo de versión; las adiciones no disruptivas (nuevos campos, nuevos endpoints) pueden agregarse en cualquier momento sin un cambio de versión.
## Relacionado [#relacionado]
Cada campo de solicitud y respuesta declarado, incluidos los objetos anidados.Genera y administra las claves que pasas en el encabezado `X-API-Key`.El DSL de filtros usado por `GET /v0/action/list`.Consulta los mismos datos de forma conversacional desde Claude, Cursor y otros clientes.
