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 vistazoCopy Anchor Link

AutenticaciónCopy Anchor Link

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 APICopy Anchor Link

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 agenteCopy Anchor Link

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.

EndpointsCopy Anchor Link

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ónCopy Anchor Link

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 APICopy Anchor Link

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 errorCopy Anchor Link

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).

VersionesCopy Anchor Link

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.

RelacionadoCopy Anchor Link