Premiers pas

Dans ce guide, vous ouvrez un ticket avec l’API REST v1, vous lisez son statut et vous ajoutez un commentaire. Il vous faut curl et une clé API.

1. Créez une clé API

Un administrateur de votre tenant crée la clé dans exoCortex Core, depuis Integrations → API keys, avec les scopes tickets:create, tickets:read et tickets:comment. La clé n’est visible qu’une seule fois : enregistrez-la dans une variable d’environnement, sans l’écrire dans le code.

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

Les détails se trouvent dans Clés API.

2. Ouvrez 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 réponse contient la clé du ticket et l’adresse pour lire son statut :

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

Vous n’indiquez pas le tenant : c’est celui de la clé. Idempotency-Key vous protège des doublons : si vous répétez la même requête avec la même clé d’idempotence, vous recevez le même ticket avec action: deduplicated. Avec external_id, vous conservez la référence à votre système.

3. Lisez le statut

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 d’un autre tenant renvoie 404, comme un ticket qui n’existe pas.

4. Ajoutez un commentaire

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. Gérez les erreurs et les limites

• Chaque erreur a ok: false et un code stable, par exemple invalid_api_key ou validation_error : fondez votre logique sur le code.
• Avec 429, attendez le nombre de secondes indiqué dans Retry-After avant de réessayer.
• Avec une erreur 5xx, réessayez avec la même Idempotency-Key.

La liste complète des codes se trouve dans Clés API.

Prochaines étapes

• Au lieu d’interroger le statut, recevez les événements avec les webhooks sortants.
• Utilisez un SDK pour ne pas écrire les appels HTTP à la main.
• Consultez la référence des Tickets pour tous les champs.