Erste Schritte

In dieser Anleitung eröffnen Sie mit der REST API v1 ein Ticket, lesen seinen Status und fügen einen Kommentar hinzu. Sie benötigen curl und einen API-Schlüssel.

1. Einen API-Schlüssel erstellen

Ein Administrator Ihres Tenants erstellt den Schlüssel in exoCortex Core unter Integrations → API keys mit den Scopes tickets:create, tickets:read und tickets:comment. Der Schlüssel wird nur einmal angezeigt: Speichern Sie ihn in einer Umgebungsvariablen, ohne ihn in den Code zu schreiben.

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

Die Details finden Sie unter API-Schlüssel.

2. Ein Ticket eröffnen

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"
  }'

Die Antwort enthält den Schlüssel des Tickets und die Adresse, unter der Sie seinen Status lesen:

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

Den Tenant geben Sie nicht an: Es ist der des Schlüssels. Idempotency-Key schützt Sie vor Duplikaten: Wenn Sie dieselbe Anfrage mit demselben Idempotenzschlüssel wiederholen, erhalten Sie dasselbe Ticket mit action: deduplicated. Mit external_id behalten Sie den Verweis auf Ihr System.

3. Den Status lesen

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"
  }
}

Ein Ticket eines anderen Tenants antwortet mit 404, genau wie ein Ticket, das nicht existiert.

4. Einen Kommentar hinzufügen

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. Fehler und Limits behandeln

• Jeder Fehler hat ok: false und einen stabilen code, zum Beispiel invalid_api_key oder validation_error: Bauen Sie die Logik auf code auf.
• Bei 429 warten Sie die in Retry-After angegebenen Sekunden ab, bevor Sie es erneut versuchen.
• Bei einem 5xx-Fehler wiederholen Sie die Anfrage mit demselben Idempotency-Key.

Die vollständige Liste der Codes finden Sie unter API-Schlüssel.

Nächste Schritte

• Statt den Status abzufragen, empfangen Sie die Ereignisse mit ausgehenden Webhooks.
• Verwenden Sie ein SDK, damit Sie die HTTP-Aufrufe nicht von Hand schreiben müssen.
• Sehen Sie in der Referenz zu Tickets alle Felder ein.