Primeros pasos

En esta guía abres un ticket con la REST API v1, lees su estado y agregas un comentario. Necesitas curl y una clave de API.

1. Crea una clave de API

Un administrador de tu tenant crea la clave en exoCortex Core, desde Integrations → API keys, con los scopes tickets:create, tickets:read y tickets:comment. La clave se ve una sola vez: guárdala en una variable de entorno, sin escribirla en el código.

export EXO_API_KEY='nhk.<keyid>.<secret>'

Los detalles están en Claves de API.

2. Abre un ticket

curl -X POST "https://exocortex-api.ai-exo-cortex.com/api/v1/tickets" \
  -H "Authorization: Bearer $EXO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  --data '{
    "subject": "Payment gateway returns HTTP 502",
    "description": "Checkout fails for all EU customers since 09:12 UTC.",
    "priority": "High",
    "external_id": "INC-88231"
  }'

La respuesta contiene la clave del ticket y la dirección para leer su estado:

{
  "ok": true,
  "ticket_key": "ACME-1042",
  "action": "created",
  "status_url": "/api/v1/tickets/ACME-1042"
}

El tenant no se indica: es el de la clave. Idempotency-Key te protege de los duplicados: si repites la misma solicitud con la misma clave de idempotencia, recibes el mismo ticket con action: deduplicated. Con external_id guardas la referencia a tu sistema.

3. Lee el estado

curl "https://exocortex-api.ai-exo-cortex.com/api/v1/tickets/ACME-1042" \
  -H "Authorization: Bearer $EXO_API_KEY"

{
  "ok": true,
  "ticket": {
    "key": "ACME-1042",
    "summary": "Payment gateway returns HTTP 502",
    "status": "In Progress",
    "priority": "High",
    "assignee": "Jane Doe",
    "created": "2026-11-01T09:14:05.000Z",
    "updated": "2026-11-01T09:31:47.000Z"
  }
}

Un ticket de otro tenant responde 404, igual que un ticket que no existe.

4. Agrega un comentario

curl -X POST "https://exocortex-api.ai-exo-cortex.com/api/v1/tickets/ACME-1042/comment" \
  -H "Authorization: Bearer $EXO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{ "comment": "Rollback completed, monitoring for 30 minutes." }'

5. Maneja errores y límites

• Cada error tiene ok: false y un code estable, por ejemplo invalid_api_key o validation_error: basa la lógica en el code.
• Con 429, espera los segundos indicados en Retry-After antes de reintentar.
• Con un error 5xx, reintenta con la misma Idempotency-Key.

La lista completa de códigos está en Claves de API.

Próximos pasos

• En lugar de consultar el estado, recibe los eventos con los webhooks salientes.
• Usa un SDK para no escribir a mano las llamadas HTTP.
• Consulta la referencia de Tickets para ver todos los campos.