Developer Guide

Developer Guide

For Developers and API Integrators

Complete API reference for building custom integrations and applications with the Overwatch platform.

API Overview

Base Information

• Base URL: https://your-organization.overwatch.com/api/v1
• Protocol: HTTPS only
• Format: JSON
• Authentication: Bearer tokens (JWT) or API keys
• Versioning: URL path versioning (/api/v1/)

Interactive Documentation

Swagger UI

Live API testing and exploration interface.

Access: /docs on your instance

ReDoc

Alternative documentation view with better organization.

Access: /redoc on your instance

OpenAPI Spec

Machine-readable API specification for tooling.

Access: /openapi.json

Quick Start

1. Authentication

JWT (User Sessions)

Login and Obtain Token:

curl -X POST "https://your-org.overwatch.com/api/v1/auth/login" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=user@company.com&password=your-password"

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 3600
}

Use Token:

curl -X GET "https://your-org.overwatch.com/api/v1/incidents" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

API Keys (Services)

Generate API Key:

curl -X POST "https://your-org.overwatch.com/api/v1/api-keys" \
  -H "Authorization: Bearer your-jwt-token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI/CD Integration",
    "permissions": ["incidents:read", "incidents:create"]
  }'

Use API Key:

curl -X GET "https://your-org.overwatch.com/api/v1/incidents" \
  -H "X-API-Key: overwatch_ak_1234567890abcdef"

2. Core Operations

Create an Incident:

curl -X POST "https://your-org.overwatch.com/api/v1/incidents" \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Database Connection Timeout",
    "severity": "high",
    "description": "Multiple services experiencing database connection timeouts"
  }'

List Incidents with Filtering:

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

Execute a Procedure:

curl -X POST "https://your-org.overwatch.com/api/v1/procedures/{procedure_id}/execute" \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "context": {
      "incident_id": "incident-uuid",
      "urgency": "high"
    }
  }'

API Capabilities

Incident Management

Complete incident lifecycle management with AI-powered suggestions.

View API →

Procedure Automation

Create, execute, and track runbook procedures with approval workflows.

View API →

AI Search

Semantic search across incidents, procedures, and knowledge base.

View API →

Real-time Updates

WebSocket connections for live collaboration and monitoring.

View API →

Analytics & Reporting

Performance metrics, team analytics, and custom reports.

View API →

Integration Management

Connect monitoring platforms and external services.

View API →

Data Entities

Core Resources:

Entity	Description	API Endpoint
Organizations	Multi-tenant organization management	/api/v1/organizations
Users	User profiles, authentication, permissions	/api/v1/users
Incidents	Complete incident lifecycle management	/api/v1/incidents
Procedures	Runbook creation and execution	/api/v1/procedures
Executions	Procedure execution tracking	/api/v1/executions
Integrations	External service configuration	/api/v1/integrations
Analytics	Performance metrics and reporting	/api/v1/analytics

SDKs and Tools

Official SDKs

JavaScript/Node.js

Installation:

npm install @overwatch/api-client

Basic Usage:

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

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

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

// Real-time updates
client.subscribe('incidents', (event) => {
  console.log('Incident update:', event);
});

Full SDK Docs →

Python

Installation:

pip install overwatch-api-client

Basic Usage:

from overwatch import OverwatchClient

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

# Create incident
incident = client.incidents.create(
    title='Database Connection Issues',
    severity='high'
)

# Real-time updates
@client.on('incident.updated')
def handle_update(event):
    print(f'Incident updated: {event.data.title}')

Full SDK Docs →

Development Tools

• Postman Collection: Download from platform
• Insomnia Collection: API collection available
• OpenAPI Generator: Generate clients from /openapi.json

Common Integration Patterns

Monitoring Platform Integration

Receive alerts from monitoring platforms and automatically create incidents:

# Incoming webhook from Datadog
curl -X POST "https://your-org.overwatch.com/api/v1/webhooks/datadog" \
  -H "Content-Type: application/json" \
  -d '{
    "alert_id": "12345",
    "alert_name": "High Error Rate",
    "severity": "critical",
    "metrics": {"error_rate": 7.2}
  }'

View Integration Guide →

CI/CD Pipeline Integration

Create incidents from deployment failures and execute rollback procedures:

# Create incident from pipeline failure
curl -X POST "/api/v1/incidents" \
  -H "X-API-Key: ci-cd-key" \
  -d '{
    "title": "Deployment Failed: API v2.1.5",
    "severity": "high",
    "context": {"pipeline_id": "pipeline-123"}
  }'

# Execute rollback procedure
curl -X POST "/api/v1/procedures/rollback-deployment/execute" \
  -H "X-API-Key: ci-cd-key" \
  -d '{"context": {"deployment_version": "v2.1.5"}}'

ITSM Integration

Sync incidents with external ITSM systems bidirectionally:

# Configure outbound webhook to ITSM
curl -X POST "/api/v1/webhooks/outbound" \
  -H "Authorization: Bearer your-token" \
  -d '{
    "name": "ITSM Sync",
    "url": "https://itsm.company.com/api/tickets",
    "events": ["incident.created", "incident.resolved"]
  }'

Rate Limiting

Per-User Limits

• Interactive Users: 1,000 requests per hour
• API Keys: 5,000 requests per hour (configurable)
• Webhook Endpoints: 10,000 requests per hour
• Search Queries: 500 AI searches per hour

Per-Organization Limits

Based on subscription plan and usage quotas.

Rate Limit Headers:

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

View Error Handling →

API Documentation Sections

Authentication

JWT tokens, API keys, SSO, and permission models.

Learn More →

Incidents API

Create, manage, and resolve incidents with AI suggestions.

Learn More →

Procedures API

Runbook management and execution with approval workflows.

Learn More →

Search & AI

Semantic search and AI-powered features.

Learn More →

WebSocket API

Real-time updates and collaboration features.

Learn More →

Error Handling

Error responses, retry logic, and rate limiting.

Learn More →

Best Practices

Authentication

1. Use API Keys for Services: Long-lived integrations should use API keys
2. JWT for User Sessions: Interactive applications use JWT with refresh tokens
3. Scope Permissions: Grant minimum necessary permissions
4. Rotate Keys: Regularly rotate API keys and monitor usage

Request Optimization

1. Use Filtering: Apply filters at API level to reduce data transfer
2. Implement Pagination: Use limit and offset for large result sets
3. Cache Responses: Cache frequently accessed data with appropriate TTL
4. Batch Operations: Use bulk endpoints when available

Error Handling

1. Implement Retry Logic: Exponential backoff for transient failures
2. Monitor Rate Limits: Check rate limit headers and queue requests
3. Handle 429 Responses: Respect Retry-After headers
4. Log Request IDs: Include request_id in error reports

Real-time Features

1. Use WebSocket for Updates: Subscribe to real-time events instead of polling
2. Handle Reconnections: Implement automatic reconnection logic
3. Filter Subscriptions: Subscribe only to needed events
4. Monitor Connection Health: Ping/pong to detect dead connections

Support and Resources

Documentation

• Authentication - Complete auth guide
• Incidents API - Incident management
• Procedures API - Runbook automation
• WebSocket API - Real-time features
• Error Handling - Errors and rate limits

Tools

• Swagger UI: /docs - Interactive API testing
• ReDoc: /redoc - Alternative documentation view
• OpenAPI Spec: /openapi.json - Machine-readable spec

SDK Documentation

• JavaScript/Node.js SDK - Official JS SDK
• Python SDK - Official Python SDK

Integration Guides

• Monitoring Platforms - Datadog, New Relic, Grafana
• CI/CD - Jenkins, GitHub Actions, GitLab CI
• ITSM - ServiceNow, Jira Service Management

Need Help?

For API questions and integration support, contact support@overwatch-observability.com.

---

Related Documentation:

• User Guide - Platform usage
• Admin Guide - Administrative functions
• Integrations - Platform integrations