Optral Documentation
API Reference

REST API

Integrate Optral with your tools and workflows using our REST API.

Authentication

All API requests require authentication using an API key

Creating an API Key

  1. Navigate to Settings
  2. Click "API Keys" tab
  3. Click "Create API Key"
  4. Copy and securely store the key - it won't be shown again

Using the API Key

Include your API key in the Authorization header:

curl -H "Authorization: Bearer mht_YOUR_API_KEY" \
  https://api.optral.ai/v1/clusters

Base URL

https://api.optral.ai/v1

Endpoints

Clusters

GET
/clusters

List all clusters in your organization

GET
/clusters/:id

Get details for a specific cluster

POST
/clusters

Create a new cluster

PATCH
/clusters/:id

Update cluster settings

DELETE
/clusters/:id

Delete a cluster

Issues

GET
/issues

List issues. Supports filtering by cluster, severity, status, type.

GET
/issues/:id

Get details for a specific issue including analysis

POST
/issues/:id/analyze

Trigger AI analysis for an issue

PATCH
/issues/:id

Update issue status (resolve, acknowledge)

Runbooks

GET
/runbooks

List all runbooks

GET
/runbooks/:id

Get runbook details and recent executions

POST
/runbooks

Create a new runbook

POST
/runbooks/:id/execute

Execute a runbook manually

Resources

GET
/resources

List Kubernetes resources. Filter by cluster, kind, namespace.

GET
/resources/:id

Get resource details including YAML manifest

Agent Connection

How Optral agents connect to the control plane

Outbound-only connection

Agents initiate the connection - no ingress rules needed in your cluster

mTLS encryption

All traffic is encrypted with mutual TLS authentication

Bi-directional communication

Agents push data and receive commands through the same tunnel

Real-time Events (SSE)

Subscribe to live updates via Server-Sent Events

GET
/events/stream

Subscribe to real-time events. Returns a stream of server-sent events.

Event Types

issue.createdissue.resolvedissue.updatedcluster.onlinecluster.offlinerunbook.startedrunbook.completedanalysis.ready
const events = new EventSource('/api/events', {
  headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
});

events.addEventListener('issue.created', (e) => {
  const issue = JSON.parse(e.data);
  console.log('New issue:', issue);
});

Rate Limits

API rate limits depend on your plan:

Free100 requests/hour
Pro1,000 requests/hour
Team5,000 requests/hour
EnterpriseCustom limits

Rate limit headers are included in all responses:X-RateLimit-Limit,X-RateLimit-Remaining,X-RateLimit-Reset

Example: List Issues

curl -X GET "https://api.optral.ai/v1/issues?status=open&severity=critical" \
  -H "Authorization: Bearer mht_YOUR_API_KEY" \
  -H "Content-Type: application/json"

# Response
{
  "issues": [
    {
      "id": "iss_abc123",
      "type": "OOMKilled",
      "severity": "critical",
      "status": "open",
      "cluster": "production-us-east",
      "resource": "api-server-7d4f8b9c6-xk2lm",
      "namespace": "default",
      "detectedAt": "2024-01-15T10:30:00Z",
      "hasAnalysis": true
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 20
}

OpenAPI Specification

A complete OpenAPI 3.0 specification is available for code generation and API exploration.

Download OpenAPI SpecOpen in Swagger Editor