Cordant docs

Cordant is an autonomous SRE agent that connects to observability, alerting, and infrastructure systems. It detects anomalies, finds root causes, and runs remediation runbooks without waking a human unless one is truly needed.

This guide covers integrations, runbooks, ingest and incidents APIs, and account settings.

Observability connections

Cordant uses observability integrations for the metrics, logs, and traces needed to diagnose service incidents. Set up each integration in the Cordant dashboard at Settings > Integrations.

Alerting connections

Cordant receives incident triggers from your current alerting layer. You can keep your existing routing. Cordant runs in parallel, picking up the same alerts as on-call and beginning its response.

PagerDuty and OpsGenie support bi-directional webhooks. Cordant auto-acknowledges incidents it resolves and opens new incidents when human escalation is needed.

Communication connections

Slack is required for incident updates and operator approval requests. The Cordant Slack app needs these scopes: chat:write, channels:read, reactions:read, app_mentions:read.

Set at least one incident notification channel for each workspace. Add channels for chosen severity levels or service groups.

Infrastructure connections

Infrastructure integrations let Cordant act on services while running a runbook. Every such action follows the authorization model in the Runbooks section.

Kubernetes requires a ServiceAccount with RBAC scoped to the required namespaces and resource types. The setup wizard includes minimum rules for scale and restart actions.

Webhook ingest

The webhook ingest endpoint accepts alert payloads from any source able to POST JSON. Use it for custom monitoring, internal alert scripts, or tools absent from the native integrations catalog.

POST https://api.trycordant.com/v1/ingest/webhook
Authorization: Bearer <api_key>
Content-Type: application/json

{
  "source": "custom-monitor",
  "service": "payments-api",
  "severity": "high",
  "title": "p99 latency exceeded 800ms",
  "context": {
    "metric": "http.response.p99",
    "current_value": 1243,
    "threshold": 800
  }
}

The source and service fields are required. The optional context object improves Cordant's initial diagnosis. See the API reference for the complete field schema.

Runbook basics

A Cordant runbook is an ordered set of diagnostic and remediation steps linked to a trigger condition. Author runbooks in the dashboard UI or send them through the runbooks API as YAML.

Each runbook step defines a type, parameters, and authorization level. That level determines whether Cordant runs it automatically or waits for operator approval.

Action types

• query: Read-only data fetch from a connected observability source. Always auto-executed.
• scale: Adjust Kubernetes deployment replica count. Requires level: auto or operator approval depending on the direction (scale-up is typically auto; scale-down requires approval).
• restart: Rolling restart of a Kubernetes deployment or StatefulSet. Requires level: approve by default.
• notify: Post a message to Slack with diagnostic context. Always auto-executed.
• webhook: POST to a configured outbound webhook. Auto-executed if marked safe in the runbook; otherwise requires approval.

Authorization levels

Each action step uses auto or approve. Auto steps run without operator input. Approve steps send a request to the incident Slack channel and wait for operator confirmation.

Approval requests expire after 15 minutes by default. Without a response, Cordant escalates through PagerDuty and waits for a human to assume control.

Ingest API

The ingest API provides one endpoint for alert payloads. Requests need a valid API key in the Authorization header. Create and manage keys at Settings > API Keys.

Incidents API

The incidents API provides read access to completed and active incident records. Use it to supply postmortem tools, ticketing systems, or custom dashboards with incident data.

Runbooks API

Use the runbooks API to create, update, or delete runbooks in code. It is the preferred option for teams keeping runbooks in version control with infrastructure code.

API access

API requests use Bearer tokens. Tokens are scoped to a workspace and support read-only or read-write access. They do not expire by default and can be rotated or revoked anytime in the dashboard.

Workspaces

A workspace contains Cordant's integrations, runbooks, incidents, and team members. Most organizations use one workspace. Create additional workspaces when separate infrastructure environments must not share runbook context.

Team members

Invite team members by email in workspace settings. Admin has full settings access; Member can author runbooks and view incidents; Viewer has read-only access. The workspace creator is always an Admin.

SSO

Enterprise workspaces support SAML 2.0 SSO with any standards-compliant identity provider. Contact [email protected] to provision your organization's SSO credentials.

Billing

Manage subscriptions and view invoice history at Settings > Billing. Plan changes begin in the next billing cycle. Enterprise contracts are managed outside the self-serve portal.