API Overview

API Overview

The Overwatch API provides a comprehensive set of endpoints to interact with the platform programmatically. It allows you to manage incidents, search for solutions, configure integrations, and more.

Base URL

All API endpoints are prefixed with /api/v1.

• Production: https://api.overwatch-observability.com/api/v1
• Development: http://localhost:8000/api/v1

Authentication

The API uses JWT (JSON Web Token) for authentication. You must include the token in the Authorization header of your requests.

Authorization: Bearer <your_access_token>

Getting a Token

To obtain a token, use the login endpoint:

POST /api/v1/auth/login

{
  "email": "your_email@example.com",
  "password": "your_password"
}

The response will contain an access_token and a refresh_token.

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 3600,
  "user": {
    "id": "user_123",
    "email": "your_email@example.com",
    "name": "John Doe",
    "role": "admin"
  }
}

Token Expiration & Refresh

Access tokens expire after 1 hour. You can use the refresh token to obtain a new access token without re-entering credentials.

POST /api/v1/auth/refresh

{
  "refresh_token": "your_refresh_token"
}

Rate Limiting

To ensure fair usage and system stability, API requests are rate-limited. The limits are applied per organization and per user.

Response headers provide information about your current rate limit status:

• X-RateLimit-Limit: The maximum number of requests allowed in the current window.
• X-RateLimit-Remaining: The number of requests remaining in the current window.
• X-RateLimit-Reset: The time (in UTC epoch seconds) when the rate limit window resets.

If you exceed the limit, the API will return a 429 Too Many Requests response.

Response Format

The API uses standard HTTP status codes and returns data in JSON format.

Success Response

{
  "data": {
    "id": "inc_12345",
    "title": "High Latency in API",
    "status": "active"
  },
  "meta": {
    "total": 1,
    "page": 1
  }
}

Error Response

{
  "error": "Validation error",
  "status_code": 422,
  "timestamp": "2025-11-21T14:30:00.000Z",
  "path": "/api/v1/incidents"
}

Key Resources

Authentication (/auth)

• POST /auth/login: Authenticate and get tokens.
• POST /auth/register: Register a new user account.
• POST /auth/refresh: Refresh access token.
• POST /auth/logout: Logout and revoke tokens.
• GET /auth/me: Get current user profile.
• POST /auth/password/reset: Request password reset.

Search (/search)

Perform semantic searches against the vector database to find relevant incidents, procedures, and solutions.

• POST /search/query: Search for solutions based on a query string or error log.

Incidents (/incidents)

Manage the full lifecycle of incidents.

• GET /incidents: List incidents.
• POST /incidents: Create a new incident.
• GET /incidents/{id}: Get incident details.
• PATCH /incidents/{id}: Update incident status or details.

Integrations (/integrations)

Configure connections to external observability platforms.

• GET /integrations: List configured integrations.
• POST /integrations: Add a new integration (e.g., Datadog, New Relic).

Procedures (/procedures)

Manage runbooks and standard operating procedures.

• GET /procedures: List procedures.
• POST /procedures: Create a new procedure.

Users (/users)

Manage user accounts and profiles.

Organizations (/organizations)

Manage organization settings, members, and subscription plans.

SDKs

Official SDKs are coming soon for:

• Python
• JavaScript/TypeScript
• Go

In the meantime, you can generate a client using our OpenAPI Specification.