API Reference

The OpsKnight API lets you programmatically manage incidents, integrate monitoring tools, query schedules, and automate your incident management workflows.

API Endpoints Overview

Endpoint	Description	Common Use Cases
Events API	Trigger, acknowledge, resolve incidents	Monitoring integrations
Incidents API	List, create, update incidents	Custom dashboards, automation
Services API	Manage services	Service catalog automation
Schedules API	Query on-call schedules	Who's on-call integrations
Users API	Manage users	User provisioning
Teams API	Manage teams	Team automation

Authentication

All API requests require authentication. OpsKnight supports API key authentication.

Creating an API Key

Go to Settings → API Keys
Click Create API Key
Enter a name (e.g., "Datadog Integration")
Select scopes (permissions)
Copy the key — it's only shown once!

Using Your API Key

Include the API key in the Authorization header:

# Bearer token format (recommended)
curl -H "Authorization: Bearer sk_live_abc123..." \
  https://opsknight.yourco.com/api/incidents

# Alternative: Api-Key format
curl -H "Authorization: Api-Key sk_live_abc123..." \
  https://opsknight.yourco.com/api/incidents

# Alternative: X-API-Key header
curl -H "X-API-Key: sk_live_abc123..." \
  https://opsknight.yourco.com/api/incidents

API Key Prefixes

Prefix	Type	Description
`sk_live_`	Production	Full access based on scopes
`sk_test_`	Test	Sandbox/test environment

Scopes

API keys have scoped permissions. Select only what you need:

Scope	Description
`events:write`	Send events (trigger, acknowledge, resolve)
`incidents:read`	Read incidents and incident details
`incidents:write`	Create and update incidents
`services:read`	Read services
`services:write`	Create and update services
`schedules:read`	Read schedules and on-call
`schedules:write`	Create and update schedules
`users:read`	Read users
`users:write`	Manage users (admin)
`teams:read`	Read teams
`teams:write`	Manage teams

Base URL

All API endpoints are relative to your OpsKnight instance:

https://your-opsknight-instance.com/api

Example:

https://opsknight.yourco.com/api/incidents

Request Format

Headers

Content-Type: application/json
Authorization: Bearer sk_live_abc123...

Request Body

JSON format for POST/PATCH requests:

{
  "title": "High CPU on web-01",
  "urgency": "HIGH",
  "service_id": "svc_abc123"
}

Response Format

Success Response

{
  "data": {
    "id": "inc_abc123",
    "title": "High CPU on web-01",
    "status": "OPEN",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

List Response (Paginated)

{
  "data": [
    { "id": "inc_abc123", "title": "..." },
    { "id": "inc_def456", "title": "..." }
  ],
  "pagination": {
    "total": 150,
    "limit": 25,
    "offset": 0,
    "has_more": true
  }
}

Error Response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Title is required",
    "details": {
      "field": "title",
      "reason": "required"
    }
  }
}

Error Codes

Code	HTTP Status	Description
`UNAUTHORIZED`	401	Invalid or missing API key
`FORBIDDEN`	403	API key lacks required scope
`NOT_FOUND`	404	Resource not found
`VALIDATION_ERROR`	400	Invalid request data
`CONFLICT`	409	Resource conflict (e.g., duplicate)
`RATE_LIMITED`	429	Too many requests
`INTERNAL_ERROR`	500	Server error

Rate Limits

API requests are rate limited to ensure fair usage:

Endpoint Type	Limit	Window
Events API	100 requests	per minute
Read endpoints	300 requests	per minute
Write endpoints	100 requests	per minute

Rate Limit Headers

Every response includes rate limit information:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1705318800

Handling Rate Limits

When rate limited, you'll receive a 429 response:

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests. Retry after 30 seconds.",
    "retry_after": 30
  }
}

Best practices:

Implement exponential backoff
Respect the Retry-After header
Cache responses where appropriate
Batch requests when possible

Pagination

List endpoints support pagination:

Parameter	Default	Max	Description
`limit`	25	100	Items per page
`offset`	0	-	Skip N items

Example

# First page
GET /api/incidents?limit=25&offset=0

# Second page
GET /api/incidents?limit=25&offset=25

# Third page
GET /api/incidents?limit=25&offset=50

Response

{
  "data": [...],
  "pagination": {
    "total": 150,
    "limit": 25,
    "offset": 25,
    "has_more": true
  }
}

Filtering

List endpoints support filtering via query parameters:

Incidents API Filters

GET /api/incidents?status=OPEN&urgency=HIGH&service_id=svc_abc123

Filter	Values	Description
`status`	OPEN, ACKNOWLEDGED, RESOLVED, SNOOZED, SUPPRESSED	Incident status
`urgency`	HIGH, MEDIUM, LOW	Urgency level
`service_id`	Service ID	Filter by service
`team_id`	Team ID	Filter by team
`assignee_id`	User ID	Filter by assignee
`created_after`	ISO 8601 date	Created after date
`created_before`	ISO 8601 date	Created before date

Multiple Values

Some filters accept multiple values:

GET /api/incidents?status=OPEN,ACKNOWLEDGED&urgency=HIGH,MEDIUM

Sorting

List endpoints support sorting:

GET /api/incidents?sort=created_at&order=desc

Parameter	Values	Default
`sort`	created_at, updated_at, urgency, status	created_at
`order`	asc, desc	desc

Quick Start Examples

Trigger an Incident

curl -X POST https://opsknight.yourco.com/api/events \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_live_abc123" \
  -d '{
    "routing_key": "payment-api",
    "event_action": "trigger",
    "dedup_key": "high-cpu-web01",
    "payload": {
      "summary": "High CPU on web-01",
      "severity": "critical",
      "source": "datadog"
    }
  }'

List Open Incidents

curl -X GET "https://opsknight.yourco.com/api/incidents?status=OPEN" \
  -H "Authorization: Bearer sk_live_abc123"

Acknowledge an Incident

curl -X POST https://opsknight.yourco.com/api/events \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_live_abc123" \
  -d '{
    "routing_key": "payment-api",
    "event_action": "acknowledge",
    "dedup_key": "high-cpu-web01"
  }'

Get Current On-Call

curl -X GET "https://opsknight.yourco.com/api/schedules/sch_abc123/on-call" \
  -H "Authorization: Bearer sk_live_abc123"

SDKs and Libraries

Official Tools

CLI Tool: CLI Documentation

Community Tools

Python SDK (community)
Node.js SDK (community)
Go SDK (community)

Webhooks (Outbound)

OpsKnight can send webhooks to your systems when events occur.

Supported Events

Event	Description
`incident.triggered`	New incident created
`incident.acknowledged`	Incident acknowledged
`incident.resolved`	Incident resolved
`incident.escalated`	Incident escalated to next step
`incident.assigned`	Incident assigned/reassigned

Webhook Payload

{
  "event": "incident.triggered",
  "timestamp": "2024-01-15T10:30:00Z",
  "incident": {
    "id": "inc_abc123",
    "title": "High CPU on web-01",
    "status": "OPEN",
    "urgency": "HIGH",
    "service": {
      "id": "svc_xyz",
      "name": "Payment API"
    },
    "assignee": {
      "id": "usr_123",
      "name": "Alice Smith"
    }
  }
}

Signature Verification

Webhooks include an HMAC-SHA256 signature:

X-OpsKnight-Signature: sha256=abc123def456...

Verify by computing HMAC of the raw request body using your webhook secret.

API Changelog

v1 (Current)

Initial stable API release
Full incident management
Events API (PagerDuty-compatible)
Schedules and on-call queries
User and team management

Need Help?

Check the CLI Tool for command-line access
See Events API for alert integration
See Incidents API for incident management
Report issues on GitHub