Subscribe
IsDown is a status page aggregator for monitoring all your vendors.

IsDown - Dev - API Documentation

The IsDown - Dev API provides programmatic access to our status page data. Monitor component status, track incidents, and retrieve scheduled maintenance information in real-time.

Overview

The StatusRay API is organized around REST principles. Our API has predictable resource-oriented URLs, returns JSON-encoded responses, and uses standard HTTP response codes.

Base URL: All API requests should be made to https://statusray.isdown.app/api/v1

Response Format

All API responses return JSON data with consistent formatting. Successful responses include the requested data, while errors return standardized error messages.

Success Response

{ "page": { "id": "a1b2c3d4e5f6", "name": "IsDown - Dev", "url": "https://statusray.isdown.app", "updated_at": "2025-11-08T06:54:28Z" }, // ... endpoint specific data }

Error Response

{ "error": "Status page not found" }

Status

Get the current overall status of your status page.

GET /api/v1/status

Returns the current status indicator and description for the status page.

Example Response

{ "page": { "id": "a1b2c3d4e5f6", "name": "IsDown - Dev", "url": "https://statusray.isdown.app", "updated_at": "2025-11-08T06:54:28Z" }, "status": { "indicator": "ok", "description": "All Systems Operational" } }

Summary

Get a comprehensive summary of your status page including current status, components, active incidents, and scheduled maintenances.

GET /api/v1/summary

Returns all status page information in a single request.

Example Response

{ "page": { "id": "a1b2c3d4e5f6", "name": "IsDown - Dev", "url": "https://statusray.isdown.app", "updated_at": "2025-11-08T06:54:28Z" }, "status": { "indicator": "minor", "description": "Minor System Outage" }, "components": [ { "id": "b2c3d4e5f6a7", "name": "API", "status": "ok", "created_at": "2023-01-01T00:00:00Z", "updated_at": "2024-01-07T11:00:00Z" } ], "incidents": [ { "id": "c3d4e5f6a7b8", "name": "API Response Time Degradation", "status": "investigating", "impact": "minor", "created_at": "2024-01-07T11:30:00Z" } ], "scheduled_maintenances": [] }

Components

Components represent the various parts of your system that you're monitoring.

GET /api/v1/components

List all components for the status page.

GET /api/v1/components/:id

Get details for a specific component.

Parameter Type Description
id string The component's hex ID (12 characters)

Incidents

Incidents are events that affect the availability or performance of your services.

GET /api/v1/incidents

List the 50 most recent incidents.

GET /api/v1/incidents/unresolved

List only unresolved incidents.

GET /api/v1/incidents/:id

Get details for a specific incident including all updates.

Parameter Type Description
id string The incident's hex ID (12 characters)

Incident Structure

{ "id": "c3d4e5f6a7b8", "page_id": "a1b2c3d4e5f6", "name": "Database Connection Issues", "impact": "major", "status": "resolved", "created_at": "2024-01-07T10:00:00Z", "updated_at": "2024-01-07T12:00:00Z", "resolved_at": "2024-01-07T12:00:00Z", "shortlink": "c3d4e5f6a7b8", "incident_updates": [ { "id": "c3d4e5f6a7b8-0", "incident_id": "c3d4e5f6a7b8", "status": "investigating", "body": "We are investigating database connectivity issues.", "created_at": "2024-01-07T10:00:00Z", "affected_components": [ { "code": "b2c3d4e5f6a7", "name": "Database", "old_status": "operational", "new_status": "major" } ] } ], "components": [ { "id": "b2c3d4e5f6a7", "name": "Database", "status": "ok", "page_id": "a1b2c3d4e5f6" } ] }

Scheduled Maintenances

Scheduled maintenances are planned events that may affect service availability.

GET /api/v1/scheduled-maintenances

List the 50 most recent scheduled maintenances.

GET /api/v1/scheduled-maintenances/upcoming

List only upcoming scheduled maintenances.

GET /api/v1/scheduled-maintenances/active

List only active (ongoing) scheduled maintenances.

GET /api/v1/scheduled-maintenances/:id

Get details for a specific scheduled maintenance.

Data Types

Timestamps

All timestamps are returned in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ

IDs

All resource IDs are 12-character hexadecimal strings: a1b2c3d4e5f6

Status Values

Component Status Description
ok Component is operational
minor Minor issues affecting the component
major Major issues affecting the component
maintenance Component is under maintenance

Status Indicators

The overall status indicator is determined by the worst status among all components:

Indicator Description Priority
ok All Systems Operational Lowest
maintenance Service Under Maintenance Medium
minor Minor System Outage High
major Major System Outage Highest