API Reference

API Reference

This page provides a structured overview of every endpoint category in the Overwatch REST API. For interactive testing, open the Swagger UI at /docs on your Overwatch instance.

Base Information

Property	Value
Base URL	https://<your-instance>/api/v1
Protocol	HTTPS (HTTP allowed in local development)
Content-Type	application/json (except login, which accepts application/x-www-form-urlencoded)
Authentication	JWT Bearer token or API key
Versioning	URL path (/api/v1/)

Tip: Every Overwatch instance exposes three documentation interfaces. Swagger UI is available at /docs, ReDoc at /redoc, and the raw OpenAPI spec at /openapi.json. Use these to explore request schemas and try endpoints directly.

Authentication

All endpoints (except POST /auth/login and POST /auth/register) require authentication. Overwatch supports two methods.

JWT Bearer Token

Include the token in the Authorization header:

Authorization: Bearer <access_token>

Tokens expire after 1 hour. Use the refresh endpoint to obtain a new access token without re-authenticating.

API Key

Include the key in the X-API-Key header:

X-API-Key: <your_api_key>

API keys are long-lived and can be scoped to specific permissions. Create and manage them through the /api-keys endpoints or the Settings page in the dashboard.

Note: For a detailed walkthrough of both authentication methods, see the Authentication guide.

---

Endpoint Categories

Authentication (/auth)

Handles user login, registration, token refresh, password management, and email verification.

Method	Endpoint	Description
POST	/auth/login	Authenticate and receive access and refresh tokens
POST	/auth/register	Create a new user account and organization
POST	/auth/refresh	Exchange a refresh token for a new access token
POST	/auth/logout	Revoke the current token and clear session cookies
GET	/auth/me	Retrieve the authenticated user’s profile
POST	/auth/password/reset	Request a password reset email
POST	/auth/password/reset/confirm	Complete a password reset with the emailed token
POST	/auth/password/change	Change the current user’s password (requires current password)
POST	/auth/verify-email	Verify an email address with a verification token
POST	/auth/resend-verification	Resend the email verification link

SSO (/sso)

Single Sign-On authentication for supported identity providers (Azure AD, Okta, Google Workspace, SAML 2.0).

Method	Endpoint	Description
GET	/sso/initiate	Begin the SSO flow for a given provider
POST	/sso/callback	Handle the identity provider’s redirect callback

Incidents (/incidents)

Full lifecycle management for incidents, including creation, status updates, assignment, and search.

Method	Endpoint	Description
GET	/incidents	List incidents with filtering by status, severity, and date range
POST	/incidents	Create a new incident
GET	/incidents/{id}	Retrieve full incident details, including timeline and analysis
PATCH	/incidents/{id}	Update incident fields (status, severity, assignee, description)

Query parameters for listing:

• status — Filter by status (active, investigating, mitigated, resolved)
• severity — Filter by severity (critical, high, medium, low)
• limit / offset — Pagination controls
• search — Full-text search across title and description

Procedures (/procedures)

Create and manage operational runbooks. Execute procedures with tracked step-by-step progress.

Method	Endpoint	Description
GET	/procedures	List available procedures
POST	/procedures	Create a new procedure with steps
GET	/procedures/{id}	Retrieve procedure details
PATCH	/procedures/{id}	Update a procedure definition
DELETE	/procedures/{id}	Delete a procedure
POST	/procedures/{id}/execute	Start a new execution of this procedure

Executions (/executions)

Track and manage procedure execution instances. Each execution records the outcome of every step.

Method	Endpoint	Description
GET	/executions	List executions (optionally filtered by procedure or incident)
GET	/executions/{id}	Retrieve execution details with step statuses
PATCH	/executions/{id}	Update execution status or step outcomes

Integrations (/integrations)

Configure connections to external monitoring platforms and services.

Method	Endpoint	Description
GET	/integrations	List configured integrations
POST	/integrations	Add a new integration
GET	/integrations/{id}	Retrieve integration details
PATCH	/integrations/{id}	Update integration settings
DELETE	/integrations/{id}	Remove an integration

Platform-specific sub-routes are available for Datadog (/integrations/datadog), New Relic (/integrations/newrelic), Elasticsearch (/integrations/elasticsearch), and SigNoz (/integrations/signoz).

Webhooks (/webhooks)

Receive inbound alert payloads from monitoring platforms.

Method	Endpoint	Description
POST	/webhooks/{platform}	Ingest an alert from the specified platform (e.g., datadog, prometheus, grafana, pagerduty, newrelic, cloudwatch, signoz)

Each platform webhook automatically routes the payload through the appropriate alert parser.

Users (/users)

Manage user profiles and team membership within an organization.

Method	Endpoint	Description
GET	/users	List users in the organization
GET	/users/{id}	Retrieve a user profile
PATCH	/users/{id}	Update user details or role
DELETE	/users/{id}	Remove a user from the organization

API Keys (/api-keys)

Create and manage long-lived API keys for service-to-service integrations.

Method	Endpoint	Description
GET	/api-keys	List API keys for the organization
POST	/api-keys	Create a new API key with scoped permissions
DELETE	/api-keys/{id}	Revoke an API key

Search (/search)

Semantic and keyword search across incidents, procedures, and the knowledge base.

Method	Endpoint	Description
POST	/search/query	Execute a search query and return ranked results

Search uses vector embeddings for semantic matching and supports hybrid mode (combining vector similarity with keyword filtering).

Organizations (/organizations)

Manage organization details and subscription settings.

Method	Endpoint	Description
GET	/organizations	Retrieve the current organization
PATCH	/organizations	Update organization settings

Organization Settings (/organization-settings)

Fine-grained configuration for organization-level preferences.

Method	Endpoint	Description
GET	/organization-settings	Retrieve all settings
PATCH	/organization-settings	Update settings

Analytics (/analytics)

Performance metrics, MTTR tracking, and team reporting.

Method	Endpoint	Description
GET	/analytics	Retrieve analytics data with configurable date ranges and groupings

Notifications (/notifications)

Manage user notification preferences and delivery channels.

Method	Endpoint	Description
GET	/notifications	List notifications for the current user
PATCH	/notifications/{id}	Mark a notification as read

Billing (/billing)

Subscription plan management and usage tracking.

Method	Endpoint	Description
GET	/billing	Retrieve current plan and usage
POST	/billing/checkout	Initiate a plan upgrade checkout

WebSocket (/ws)

Real-time bidirectional communication for live updates.

Endpoint	Description
/api/v1/ws	Establish a WebSocket connection for real-time incident updates, alert streams, and AI chat messages

The WebSocket connection requires an authenticated token (passed as a query parameter or in the initial handshake). Events are published for incident creation, status changes, new alerts, and procedure execution updates.

Helper (/helper)

Download endpoint for the Helper CLI binary.

Method	Endpoint	Description
GET	/helper/download	Download the Helper CLI binary for the detected platform

Admin (/admin)

Administrative operations for organization owners and administrators.

Method	Endpoint	Description
GET	/admin/audit	Retrieve audit log entries
GET	/admin/stats	Retrieve system-level statistics

Audit (/audit)

Read-only access to audit log entries for compliance and debugging.

Method	Endpoint	Description
GET	/audit	Query audit log events with date and event-type filters

Logs (/logs)

Ingest and query application logs.

Method	Endpoint	Description
POST	/logs	Submit log entries for indexing
GET	/logs	Query indexed logs

---

Rate Limiting

Rate limits are applied per user and per organization. The specific limits depend on your subscription plan.

Scope	Default Limit
Interactive users	1,000 requests per hour
API keys	5,000 requests per hour
Webhook endpoints	10,000 requests per hour
AI search queries	500 per hour

Every response includes rate limit headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 997
X-RateLimit-Reset: 1709251200

When a limit is exceeded, the API returns 429 Too Many Requests with a Retry-After header indicating how many seconds to wait.

---

Error Format

All error responses follow a consistent JSON structure:

{
  "detail": "Human-readable error message",
  "status_code": 422
}

Common Status Codes

Code	Meaning
200	Success
201	Resource created
400	Bad request (validation error)
401	Unauthorized (missing or invalid token)
403	Forbidden (insufficient permissions)
404	Resource not found
422	Unprocessable entity (schema validation failure)
423	Account locked (too many failed login attempts)
429	Rate limit exceeded
500	Internal server error

Tip: Include the X-Request-ID header value from the response when reporting issues to support. It allows the team to trace the request through backend logs.

---

Pagination

List endpoints support cursor-based pagination with limit and offset query parameters.

Parameter	Type	Default	Description
limit	integer	25	Maximum number of results to return (max 100)
offset	integer	0	Number of results to skip

Paginated responses include a meta object:

{
  "data": [],
  "meta": {
    "total": 142,
    "limit": 25,
    "offset": 0
  }
}

---

Interactive Documentation

Interface	URL	Use Case
Swagger UI	/docs	Interactive endpoint testing with request builder
ReDoc	/redoc	Browsable documentation with schema details
OpenAPI Spec	/openapi.json	Machine-readable spec for code generation and tooling

Note: The Swagger UI allows you to authenticate with a Bearer token and execute requests directly against your instance. It is the fastest way to explore the API during development.