Primi passi

In questa guida apri un ticket con la REST API v1, ne leggi lo stato e aggiungi un commento. Ti servono curl e una chiave API.

1. Crea una chiave API

Un amministratore del tuo tenant crea la chiave in exoCortex Core, da Integrations → API keys, con gli scope tickets:create, tickets:read e tickets:comment. La chiave si vede una sola volta: salvala in una variabile d’ambiente, senza scriverla nel codice.

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

I dettagli sono in Chiavi API.

2. Apri 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 risposta contiene la chiave del ticket e l’indirizzo per leggerne lo stato:

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

Il tenant non si indica: è quello della chiave. Idempotency-Key ti protegge dai duplicati: se ripeti la stessa richiesta con la stessa chiave di idempotenza, ricevi lo stesso ticket con action: deduplicated. Con external_id conservi il riferimento al tuo sistema.

3. Leggi lo stato

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 di un altro tenant risponde 404, come un ticket che non esiste.

4. Aggiungi un commento

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. Gestisci errori e limiti

• Ogni errore ha ok: false e un code stabile, per esempio invalid_api_key o validation_error: basa la logica sul code.
• Con 429 aspetta i secondi indicati in Retry-After prima di riprovare.
• Con un errore 5xx riprova con la stessa Idempotency-Key.

L’elenco completo dei codici è in Chiavi API.

Prossimi passi

• Invece di interrogare lo stato, ricevi gli eventi con i webhook in uscita.
• Usa un SDK per non scrivere a mano le chiamate HTTP.
• Consulta la reference di Ticket per tutti i campi.