Respuesta de un recurso

Los endpoints que devuelven un solo recurso envuelven el contenido en data y añaden un objeto meta:

{
  "data": {
    "id": "agt_01HZ...",
    "type": "support",
    "name": "Soporte Demo",
    "created_at": "2026-04-13T14:12:00Z"
  },
  "meta": {
    "request_id": "req_01HZ..."
  }
}

Respuesta de lista

Los endpoints que devuelven colecciones usan el mismo envoltorio más información de paginación:

{
  "data": [
    { "id": "agt_01...", "type": "support", "name": "..." },
    { "id": "agt_02...", "type": "training", "name": "..." }
  ],
  "meta": {
    "request_id": "req_01HZ...",
    "pagination": {
      "has_more": true,
      "next_cursor": "agt_02..."
    }
  }
}

Ver paginación para el detalle.

Convenciones de campos

• IDs: cadenas con prefijo por tipo — agt_ (agente), cnv_ (conversación), msg_ (mensaje), ldx_ (lead), whs_ (webhook subscription), evt_ (evento).
• Fechas: ISO 8601 UTC (2026-04-13T14:12:00Z).
• Booleanos: true / false, nunca "true" / "1".
• Nulls: los campos opcionales aparecen como null, no se omiten.
• Enums: siempre strings en snake_case (type: "support", status: "active").

Cabeceras en toda respuesta

Content-Type

Todas las respuestas son application/json excepto:

• POST /v1/agents/{id}/messages con stream: true → text/event-stream (SSE).
• Descarga de archivos vía URL presignada → application/octet-stream (servido por el storage, no por la API).