Pierwsze kroki

W tym przewodniku otworzą Państwo zgłoszenie za pomocą REST API v1, odczytają jego stan i dodadzą komentarz. Potrzebne są curl i klucz API.

1. Utworzenie klucza API

Administrator Państwa tenanta tworzy klucz w exoCortex Core, w sekcji Integrations → API keys, ze scope tickets:create, tickets:read i tickets:comment. Klucz jest widoczny tylko raz: należy zapisać go w zmiennej środowiskowej, nie umieszczając go w kodzie.

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

Szczegóły znajdują się w sekcji Klucze API.

2. Otwarcie zgłoszenia

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

Odpowiedź zawiera klucz zgłoszenia i adres, pod którym można odczytać jego stan:

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

Tenanta nie trzeba wskazywać: jest nim tenant klucza. Idempotency-Key chroni przed duplikatami: jeśli to samo żądanie zostanie powtórzone z tym samym kluczem idempotencji, zwrócone zostanie to samo zgłoszenie z action: deduplicated. Pole external_id pozwala zachować odniesienie do Państwa systemu.

3. Odczytanie stanu

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

Dla zgłoszenia innego tenanta zwracany jest kod 404, tak jak dla zgłoszenia, które nie istnieje.

4. Dodanie komentarza

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. Obsługa błędów i limitów

Każdy błąd ma ok: false i stały code, na przykład invalid_api_key lub validation_error: logikę należy opierać na code.
W przypadku kodu 429 należy odczekać liczbę sekund wskazaną w Retry-After przed ponowieniem próby.
W przypadku błędu 5xx należy ponowić próbę z tym samym Idempotency-Key.

Pełna lista kodów znajduje się w sekcji Klucze API.

Kolejne kroki

Zamiast odpytywać o stan, można odbierać zdarzenia za pomocą webhooków wychodzących.
Można użyć SDK, aby nie pisać ręcznie wywołań HTTP.
Wszystkie pola opisano w dokumentacji referencyjnej Ticket.