API Reference

The Cordant API is a REST interface for querying incident data, reading policy configurations, and subscribing to workspace events. All endpoints require a workspace API key and return JSON responses.

Base URL: https://api.trycordant.com/v1

Authentication

All API requests are authenticated with a Bearer token. Include your API key in the Authorization header of every request. API keys are scoped to a workspace and carry the permissions defined in your workspace settings.

# Sample: Bearer token authentication
curl https://api.trycordant.com/v1/incidents \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json"

API keys are managed through your workspace settings. Keys can be scoped to read-only access or given write access for policy updates. Rotate keys by creating a new one and revoking the old key once all integrations are updated.

Incidents

The incidents resource exposes the active and historical incident log for your workspace. Incidents are created by the Cordant engine when correlated signals cross a threshold defined in your policy. The API returns incident records with diagnosis context and proposed actions.

List incidents

GET /v1/incidents

Returns a paginated list of incidents, ordered by start time descending. Accepts optional query parameters for filtering by status or severity.

Example response (sample data):

{
  "incidents": [
    {
      "incident_id": "inc_01HXQP9RYV7K3BZFX4G8M",
      "status": "open",
      "severity": "P2",
      "started_at": "2026-08-14T03:17:29Z",
      "signals": 4,
      "diagnosis": {
        "summary": "Memory pressure on 3 of 5 worker nodes",
        "confidence": 0.91
      },
      "proposed_action": "scale-hpa",
      "policy_approved": true
    }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6ImluY18wMUhYIn0",
    "has_more": true
  }
}

Get incident

GET /v1/incidents/:incident_id

Returns the full incident record including signal log, diagnosis chain, action history, and resolution timeline if resolved.

Update incident

PATCH /v1/incidents/:incident_id

Update the status or add a resolution note to an incident. Accepted fields: status, resolution_note.

Policy

Policy resources define what actions Cordant may take autonomously and which require human approval. Policy configuration can be read via API; writes require a key with the policy:write scope.

Get workspace policy

GET /v1/policy

Returns the active policy document for the workspace, including allowed remediation categories, approval requirements, and namespace scope rules.

Webhooks

Cordant can POST event payloads to an endpoint you configure when incidents change state. Webhooks are useful for feeding Cordant events into PagerDuty, Slack, Jira, or a custom pipeline.

Register a webhook

POST /v1/webhooks

Register an endpoint to receive event payloads. Specify the event types to subscribe to and the HTTPS URL that will receive the POST requests.

{
  "url": "https://your-pipeline.example.com/cordant-events",
  "events": [
    "incident.opened",
    "incident.escalated",
    "incident.resolved"
  ],
  "secret": "<signing-secret>"
}

Webhook payload format

All webhook events share the same envelope structure. The event field identifies the type and the payload block carries event-specific data.

{
  "event": "incident.escalated",
  "workspace": "ws_example",
  "incident_id": "inc_01HXQP9RYV7K3BZFX4G8M",
  "payload": {
    "severity": "P2",
    "title": "Memory pressure on worker nodes",
    "affected_services": ["payments-api", "worker-pool"],
    "proposed_action": "scale-hpa",
    "policy_approved": true,
    "escalation_reason": "confidence below threshold for autonomous action",
    "timestamp": "2026-08-14T03:17:42Z"
  }
}

Verify webhook signatures

Each POST request includes an X-Cordant-Signature header containing an HMAC-SHA256 signature of the raw request body using the signing secret you configured. Verify this signature before processing the payload.

import hmac, hashlib

def verify_webhook(payload_bytes, signature_header, secret):
    expected = hmac.new(
        secret.encode(),
        payload_bytes,
        hashlib.sha256
    ).hexdigest()
    received = signature_header.removeprefix("sha256=")
    return hmac.compare_digest(expected, received)

Rate Limits

API requests are rate-limited per workspace. Responses include the following headers to help you manage request pacing:

When a request exceeds the rate limit, the API returns a 429 Too Many Requests response. Implement exponential backoff in clients that make high-volume requests.

Error responses

All error responses follow the same structure: an error object with a code and a human-readable message.

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or revoked API key"
  }
}

Getting help

If you encounter API behavior that differs from this documentation or need help with a specific integration, contact [email protected]. Include the request ID from the X-Request-ID response header when reporting unexpected errors.