API Quick Reference

API Quick Reference

Quick reference for the most common API operations.

Interactive Documentation

For complete API documentation with live testing, visit /docs on your Overwatch instance.

Core Endpoints

Incidents API

Base Path: /api/v1/incidents

Common Operations:

• GET /incidents - List incidents with filtering
• POST /incidents - Create new incident
• GET /incidents/{id} - Get incident details
• PUT /incidents/{id} - Update incident
• DELETE /incidents/{id} - Delete incident
• POST /incidents/{id}/comments - Add comment

Full Documentation →

Create Incident:

curl -X POST "/api/v1/incidents" \
  -H "Authorization: Bearer your-token" \
  -d '{
    "title": "Database Connection Timeout",
    "severity": "high",
    "description": "Multiple services experiencing timeouts"
  }'

List with Filters:

curl -X GET "/api/v1/incidents?severity=critical,high&status=in_progress&limit=25" \
  -H "Authorization: Bearer your-token"

Procedures API

Base Path: /api/v1/procedures

Common Operations:

• GET /procedures - List procedures
• POST /procedures - Create procedure
• GET /procedures/{id} - Get procedure details
• POST /procedures/{id}/execute - Execute procedure
• GET /executions - List executions
• GET /executions/{id} - Get execution status

Full Documentation →

Execute Procedure:

curl -X POST "/api/v1/procedures/{procedure_id}/execute" \
  -H "Authorization: Bearer your-token" \
  -d '{
    "context": {"incident_id": "uuid", "urgency": "high"}
  }'

Search API

Base Path: /api/v1/search

Common Operations:

• POST /search - Semantic search across content
• GET /search/suggestions - AI-powered suggestions

Full Documentation →

Semantic Search:

curl -X POST "/api/v1/search" \
  -H "Authorization: Bearer your-token" \
  -d '{
    "query": "database connection timeout",
    "content_types": ["incidents", "procedures"],
    "min_confidence": 0.7
  }'

Analytics API

Base Path: /api/v1/analytics

Common Operations:

• GET /analytics/dashboard - Dashboard metrics
• GET /analytics/incidents - Incident analytics
• GET /analytics/procedures - Procedure analytics
• GET /analytics/team - Team performance
• POST /analytics/reports - Generate custom report

Full Documentation →

Integrations API

Base Path: /api/v1/integrations

Common Operations:

• GET /integrations - List integrations
• POST /integrations - Create integration
• PUT /integrations/{id} - Update integration
• POST /integrations/{id}/test - Test connection

Full Documentation →

WebSocket API

Endpoint: wss://your-org.overwatch.com/ws

Subscribe to Updates:

const ws = new WebSocket('wss://your-org.overwatch.com/ws', [], {
  headers: {'Authorization': 'Bearer your-token'}
});

// Subscribe to incidents
ws.send(JSON.stringify({
  type: 'subscribe',
  channel: 'incidents',
  filters: {severity: ['critical', 'high']}
}));

// Handle events
ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Received:', data.type, data.data);
};

Event Types:

• incident.created - New incident
• incident.updated - Incident changed
• execution.step_completed - Procedure step done
• user.online - User presence

Error Handling

HTTP Status Codes

Code	Meaning	Action
200	Success	Request completed
201	Created	Resource created
400	Bad Request	Check request format
401	Unauthorized	Check authentication
403	Forbidden	Check permissions
404	Not Found	Resource doesn’t exist
429	Rate Limited	Wait and retry
500	Server Error	Retry with backoff

Error Response Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": {"field": "severity", "issue": "Invalid value"},
    "request_id": "req-uuid"
  }
}

Retry Logic Example

async function apiCall(url, options, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);

      if (response.status === 429) {
        const retryAfter = response.headers.get('Retry-After') || 60;
        await sleep(retryAfter * 1000);
        continue;
      }

      if (response.status >= 500 && attempt < maxRetries) {
        await sleep(Math.pow(2, attempt) * 1000);
        continue;
      }

      return response;
    } catch (error) {
      if (attempt === maxRetries) throw error;
    }
  }
}

Rate Limiting

Limits

• Interactive Users: 1,000 requests/hour
• API Keys: 5,000 requests/hour (configurable)
• Webhooks: 10,000 requests/hour
• Search: 500 AI searches/hour

Headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 995
X-RateLimit-Reset: 1696768800

SDK Usage

JavaScript

const { OverwatchClient } = require('@overwatch/api-client');

const client = new OverwatchClient({
  baseURL: 'https://your-org.overwatch.com',
  apiKey: 'your-key'
});

// Create incident
const incident = await client.incidents.create({
  title: 'Issue Title',
  severity: 'high'
});

// List incidents
const incidents = await client.incidents.list({
  severity: ['critical', 'high']
});

// Execute procedure
const execution = await client.procedures.execute('procedure-id', {
  context: {incident_id: incident.id}
});

Python

from overwatch import OverwatchClient

client = OverwatchClient(
    base_url='https://your-org.overwatch.com',
    api_key='your-key'
)

# Create incident
incident = client.incidents.create(
    title='Issue Title',
    severity='high'
)

# List incidents
incidents = client.incidents.list(
    severity=['critical', 'high']
)

# Execute procedure
execution = client.procedures.execute(
    'procedure-id',
    context={'incident_id': incident.id}
)

Complete Documentation

For complete API documentation with all endpoints, parameters, and response schemas:

Swagger UI

Interactive API testing

Access at: /docs on your instance

ReDoc

Alternative documentation view

Access at: /redoc on your instance

OpenAPI Spec

Machine-readable specification

Download from: /openapi.json

Need Help?

• Authentication Guide - Auth methods
• SDK Documentation - Official SDKs
• Integration Guides - Platform integrations
• Support - Technical support