SiftDocs
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 e ingerir registros normalizados.

De un vistazo

API REST en https://api.getsift.ai✅
Leer acciones, agentes, colas, analíticas; buscar conversaciones✅
Escritura: campos personalizados, 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✅
The Sift API Swagger UI listing available endpoints
Explora los endpoints de la API REST en el Swagger UI interactivo.

Autenticación

Cada solicitud debe incluir tu clave de API en el encabezado X-API-Key:

GET /v0/action/list
X-API-Key: sk_live_your_key_here

Consulta la página de Claves de API para saber cómo generar y administrar claves, y qué puede y no puede hacer una clave.

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

Lee la referencia de campos de la API antes de construir una solicitud. Usa el OpenAPI JSON para obtener esquemas completos legibles por máquina.

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.

Endpoints

MétodoRutaDescripción
GET/v0/action/listLista acciones. Admite fullFilter, rango de fechas y orden; consulta Sintaxis de consulta
GET/v0/action/:idObtiene una sola acción
GET/v0/actions/:actionId/custom-fieldsLee los campos personalizados de una acción (requiere clave con alcance read)
PATCH/v0/actions/:actionId/custom-fieldsEstablece los campos personalizados de una acción (requiere clave con alcance write)
GET/v0/agentsLista agentes con métricas de rendimiento
GET/v0/agents/:idObtiene un solo agente
GET/v0/queuesLista colas con métricas
GET/v0/analytics/tagsEstadísticas del panel de etiquetas
GET/v0/analytics/tags/volumeVolumen de etiquetas a lo largo del tiempo
GET/v0/analytics/sentimentDistribución diaria de sentimiento
GET/v0/analytics/sentiment/by-tagSentimiento desglosado por etiqueta
GET/v0/analytics/engagementPercentiles de participación, crecimiento semanal y datos de embudo
GET/v0/conversations/searchBúsqueda de texto completo y DSL en conversaciones
POST/v0/ingest/recordsIngesta 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, ingesta normalizada y Custom API.

Importación por Custom API

Usa 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

Los errores devuelven un cuerpo JSON consistente:

{
  "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

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

On this page