Getting started

In this guide you open a ticket with the REST API v1, read its status and add a comment. You need curl and an API key.

1. Create an API key

An administrator of your tenant creates the key in exoCortex Core, from Integrations → API keys, with the scopes tickets:create, tickets:read and tickets:comment. The key is shown only once: save it in an environment variable, without writing it in your code.

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

The details are in API keys.

2. Open a 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"
  }'

The response contains the ticket key and the address to read its status:

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

You do not specify the tenant: it is the key’s tenant. Idempotency-Key protects you from duplicates: if you repeat the same request with the same idempotency key, you get the same ticket with action: deduplicated. With external_id you keep the reference to your own system.

3. Read the status

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

A ticket from another tenant returns 404, just like a ticket that does not exist.

4. Add a comment

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. Handle errors and limits

• Every error has ok: false and a stable code, for example invalid_api_key or validation_error: base your logic on the code.
• With 429, wait the number of seconds shown in Retry-After before retrying.
• With a 5xx error, retry with the same Idempotency-Key.

The full list of codes is in API keys.

Next steps

• Instead of polling the status, receive events with outbound webhooks.
• Use an SDK so you do not have to write HTTP calls by hand.
• See the Tickets reference for all fields.