Skip to content

Getting Started

This guide will help you get started with the Outage Detection System API.

Prerequisites

  • An HTTP client (curl, Postman, or your preferred library)
  • Basic understanding of REST APIs

Making Your First Request

Fetch Current Incidents

curl https://ods-api.m-8b1.workers.dev/incidents

This returns all current incidents from all data sources.

Filter by Time Window

You can filter incidents by time using query parameters:

# Last 24 hours
curl "https://ods-api.m-8b1.workers.dev/incidents?start=2025-01-14T00:00:00Z&end=2025-01-15T00:00:00Z"

Filter by Source

# Only power outages from ODIN
curl "https://ods-api.m-8b1.workers.dev/incidents?source=odin"

# Only network incidents from Cloudflare Radar
curl "https://ods-api.m-8b1.workers.dev/incidents?source=radar"

Filter by Status

# Only ongoing incidents
curl "https://ods-api.m-8b1.workers.dev/incidents?status=ongoing"

Understanding the Response

Each incident includes:

Field Description
id Unique identifier
kind Type: power or network
status Current status: ongoing or resolved
startedAt ISO 8601 timestamp when incident started
endedAt ISO 8601 timestamp when resolved (null if ongoing)
confidence Confidence score from 0-1
region Geographic region affected
source Data source identifier
lat, lon Coordinates for mapping (if available)

Checking Reachability

The reachability API provides active network probing data:

# Get all reachability statuses
curl https://ods-api.m-8b1.workers.dev/reachability

# Get status for a specific target
curl https://ods-api.m-8b1.workers.dev/reachability/cloudflare-dns

Historical Data

Access historical incident data (up to 90 days):

curl https://ods-api.m-8b1.workers.dev/incidents/history

Next Steps

SDK (Coming Soon)

We're working on official SDKs for:

  • JavaScript/TypeScript
  • Python
  • Go

MCP Server

For AI assistant integration, see our MCP Server documentation.