Primeiros passos

Neste guia abres um ticket com a REST API v1, lês o seu estado e adicionas um comentário. Precisas do curl e de uma chave de API.

1. Cria uma chave de API

Um administrador do teu tenant cria a chave no exoCortex Core, em Integrations → API keys, com os scopes tickets:create, tickets:read e tickets:comment. A chave só é mostrada uma vez: guarda-a numa variável de ambiente, sem a escreveres no código.

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

Os detalhes estão em Chaves de API.

2. Abre um 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"
  }'

A resposta contém a chave do ticket e o endereço para leres o seu estado:

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

O tenant não se indica: é o da chave. A Idempotency-Key protege-te contra duplicados: se repetires o mesmo pedido com a mesma chave de idempotência, recebes o mesmo ticket com action: deduplicated. Com external_id guardas a referência ao teu sistema.

3. Lê o estado

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

Um ticket de outro tenant responde 404, tal como um ticket que não existe.

4. Adiciona um comentário

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. Trata os erros e os limites

• Cada erro tem ok: false e um code estável, por exemplo invalid_api_key ou validation_error: baseia a lógica no code.
• Com 429, aguarda os segundos indicados em Retry-After antes de tentares de novo.
• Com um erro 5xx, tenta de novo com a mesma Idempotency-Key.

A lista completa dos códigos está em Chaves de API.

Próximos passos

• Em vez de consultares o estado, recebe os eventos com os webhooks de saída.
• Usa um SDK para não escreveres as chamadas HTTP à mão.
• Consulta a referência de Tickets para todos os campos.