Referencia de la API

Referencia para operaciones de WorkItem, controles de pasos de decisión, ejecución de integraciones y exportación de telemetría.

Estas API están diseñadas para un comportamiento de automatización predecible con alcance explícito de política e inquilino.

Endpoint base

Utiliza tu endpoint público de la API configurado para las solicitudes autenticadas.

https://api.threada.ai

Autenticación y contexto

Utiliza credenciales delimitadas para acceder a la API
Incluye el contexto de inquilino y rol cuando sea necesario
Las solicitudes sin contexto válido fallan de forma cerrada

Alcances típicos

workitems:read y workitems:write
workflow:manage para actualizaciones de políticas y decisiones
actions:execute para la ejecución gobernada
telemetry:read para exportaciones y análisis

Paginación y filtrado

Los endpoints de listado admiten paginación basada en cursor o token
Filtra por canal, flujo de trabajo, estado, versión de política y rango de tiempo
Prefiere ventanas delimitadas para exportaciones grandes de telemetría

Modelo de errores

Categorías de error tipadas para fallos de validación, autorización, política y ejecución
Los códigos de motivo permiten un manejo determinista en las herramientas del operador
Se devuelven ID de correlación para la investigación entre servicios

Solicitudes de ejemplo

Crear un WorkItem a partir de la carga de entrada

Crea un registro de trabajo canónico para el procesamiento del flujo de trabajo. Incluye el identificador del canal de entrada cuando sea necesario.

Solicitud

curl -X POST "https://api.threada.ai/api/v1/public/work-items" \
  -H "X-API-Key: <api-key>" \
  -H "Content-Type: application/json" \
  -d "{\"subject\":\"Review renewal request\",\"channel\":\"web\",\"channel_id\":\"web_main\",\"initial_message\":{\"role\":\"user\",\"content\":\"Review this renewal request before approval\"},\"tags\":[\"policy_review\"]}"

Respuesta

{
  "work_item": {
    "summary": {
      "work_item_id": "wi_123",
      "status": "new",
      "subject": "Review renewal request"
    }
  }
}

Ejecutar una acción aprobada

Ejecuta una acción aprobada por políticas contra una integración configurada.

Solicitud

curl -X POST "https://api.threada.ai/api/v1/public/work-items/wi_123/actions" \
  -H "X-API-Key: <api-key>" \
  -H "Content-Type: application/json" \
  -d "{\"integration_id\":\"int_workflow\",\"idempotency_key\":\"act_456\",\"payload\":{\"type\":\"custom_http\",\"method\":\"POST\",\"url\":\"https://api.example.com/approvals\",\"body_json\":\"{\\\"approved\\\":true}\"}}"

Respuesta

{
  "action": {
    "action_id": "act_456",
    "work_item_id": "wi_123",
    "action_type": "custom_http",
    "status": "completed"
  }
}

Artefactos de ejemplo

Ejemplos ilustrativos de los objetos que Threada produce, con datos sintéticos, no son clientes ni registros reales. Los nombres de los campos siguen los esquemas de la API y de auditoría de Threada.

¿Necesitas orientación para la implementación?

Utiliza la documentación y la descripción técnica para conocer los patrones de despliegue y gobernanza.

Contactar con el equipo técnico