API Documentation

Query third-party service status programmatically. No authentication required for public endpoints.

Overview

The StatusDrop API provides read-only access to service status data. All responses are JSON (except RSS feed and CSV export). All endpoints support CORS for browser-based access.

Base URL: https://statusdrop.dev

Rate Limits: 120 requests per minute per IP per stack. Exceeding the limit returns HTTP 429 with a Retry-After header.

Caching: Status endpoints are cached for 30 seconds at the edge. Widget data is cached for 60 seconds. The last_updated field indicates when data was last refreshed.

Stack ID: All endpoints use the stack ID as the identifier. This is the same value from your embed code data-stack attribute (a Convex document ID like jd74qt7pm0egy36kdtqcx13gm982fb2b).

For AI Agents

StatusDrop is designed to be machine-readable. When an AI agent visits a client site that uses StatusDrop:

Look for the StatusDrop widget script tag: <script src="https://statusdrop.dev/widget.js" data-stack="STACK_ID">
Extract the data-stack attribute to get the stack ID
Call GET /api/v1/status/{id} to get current status
Read the status_summary field for a human-readable description
Use _links for navigating to related endpoints (HATEOAS)

StatusDrop also provides /llms.txt and /llms-full.txt files following the llmstxt.org standard, plus JSON-LD structured data (schema.org) on all status pages for discovery by crawlers and agents.

Status Values

All status fields use one of these normalized values:

Value	Description	Color
operational	Service is running normally	Green
degraded	Service is experiencing minor issues	Yellow
partial_outage	Some components are affected	Orange
major_outage	Service is significantly impacted	Red
unknown	Status could not be determined	Gray

Endpoints

GET/api/v1/status/{id}

Get Stack Status

Returns the current status of all third-party services in a stack, including an AI-friendly summary, overall status, recent incidents, and HATEOAS navigation links. Responses are cached for 30 seconds.

Parameters

idpathThe stack ID (from your embed code data-stack attribute)

Response

{
  "stack_id": "jd74qt7pm0egy36kdtqcx13gm982fb2b",
  "stack_name": "My SaaS",
  "overall_status": "operational",
  "status_summary": "All 5 third-party services are running normally.",
  "status_header_text": "All Dependencies Online",
  "operational_count": 5,
  "total_services": 5,
  "services": [
    {
      "name": "Stripe",
      "domain": "stripe.com",
      "status": "operational",
      "last_checked": "2026-03-07T12:00:00Z",
      "status_page_url": "https://status.stripe.com"
    }
  ],
  "recent_incidents": [
    {
      "service": "AWS",
      "status": "degraded",
      "timestamp": "2026-03-07T10:30:00Z"
    }
  ],
  "status_page_url": "https://statusdrop.dev/s/jd74qt7pm0egy36kdtqcx13gm982fb2b",
  "last_updated": "2026-03-07T12:05:00Z",
  "_links": {
    "self": "https://statusdrop.dev/api/v1/status/jd74qt7pm0egy36kdtqcx13gm982fb2b",
    "services": "https://statusdrop.dev/api/v1/status/jd74qt7pm0egy36kdtqcx13gm982fb2b/services",
    "history": "https://statusdrop.dev/api/v1/status/jd74qt7pm0egy36kdtqcx13gm982fb2b/history",
    "openapi": "https://statusdrop.dev/api/v1/openapi"
  }
}

GET/api/v1/status/{id}/services

Get Detailed Services

Returns a detailed list of all visible services in a stack with check times, display order, and status page URLs.

Parameters

idpathThe stack ID (from your embed code data-stack attribute)

Response

{
  "stack_id": "jd74qt7pm0egy36kdtqcx13gm982fb2b",
  "stack_name": "My SaaS",
  "total": 5,
  "services": [
    {
      "name": "Stripe",
      "domain": "stripe.com",
      "status": "operational",
      "status_page_url": "https://status.stripe.com",
      "last_checked": "2026-03-07T12:00:00Z",
      "order": 0
    }
  ]
}

GET/api/v1/status/{id}/history

Get Status History

Returns status change events for a stack over a specified time period. Supports JSON and CSV export. Useful for tracking incidents and calculating uptime.

Parameters

idpathThe stack ID (from your embed code data-stack attribute)

daysqueryNumber of days of history (1-30, default: 7)

formatqueryResponse format: "json" (default) or "csv" (downloads a CSV file)

Response

{
  "stack_id": "jd74qt7pm0egy36kdtqcx13gm982fb2b",
  "stack_name": "My SaaS",
  "period_days": 7,
  "total_events": 3,
  "events": [
    {
      "service": "AWS",
      "domain": "aws.amazon.com",
      "old_status": "operational",
      "status": "degraded",
      "timestamp": "2026-03-01T14:30:00Z"
    }
  ]
}

GET/api/v1/status/{id}/feed

RSS Feed

Returns an RSS 2.0 feed of status change events for a stack. Subscribe in any RSS reader to track incidents. Each item includes the service name, old status, new status, and timestamp.

Parameters

idpathThe stack ID (from your embed code data-stack attribute)

Response

<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="...">
  <channel>
    <title>My SaaS - Service Status</title>
    <item>
      <title>AWS: Operational → Degraded</title>
      <description>AWS status changed from Operational to Degraded</description>
      <pubDate>Sat, 01 Mar 2026 14:30:00 GMT</pubDate>
    </item>
  </channel>
</rss>

GET/api/widget/{id}

Widget Data

Returns widget configuration and service statuses optimized for the embeddable widget. Can also be used for custom integrations. Cached for 60 seconds.

Parameters

idpathThe stack ID (same as data-stack attribute in embed code)

Response

{
  "stackName": "My SaaS",
  "slug": "my-saas",
  "services": [
    {
      "name": "Stripe",
      "domain": "stripe.com",
      "status": "operational",
      "faviconUrl": "...",
      "showLogo": true,
      "isClickable": true
    }
  ],
  "config": {
    "template": "minimal-dot",
    "theme": "light",
    "showStatusPageLink": true,
    "showBranding": true
  },
  "statusPageUrl": "https://statusdrop.dev/s/...",
  "lastUpdated": "2026-03-07T12:00:00Z"
}

GET/api/v1/health

Health Check

Returns the API health status. Use this for uptime monitoring of the StatusDrop API itself.

Response

{
  "status": "ok",
  "version": "1.0",
  "service": "StatusDrop API",
  "timestamp": "2026-03-07T12:00:00Z"
}

GET/api/v1/openapi

OpenAPI Specification

Returns the OpenAPI 3.1.0 specification for all v1 endpoints. Use this to auto-generate client libraries or integrate with API tools like Postman.

Response

{ "openapi": "3.1.0", "info": { ... }, "paths": { ... } }

Authenticated API (Pro)

Pro users get one API key per account to manage stacks, services, and catalog publishing programmatically. Generate your key in Settings on the dashboard. Keys are SHA-256 hashed before storage and shown only once at creation.

Authentication: Authorization: Bearer sd_live_your_key_here

If your plan is downgraded to Free, your API key is automatically revoked and all authenticated endpoints will return 401.

GET/api/v1/stacksAuth Required

List Stacks

Returns all stacks owned by the API key holder with service counts and overall status.

Response

[
  {
    "_id": "jd74qt7pm0egy36kdtqcx13gm982fb2b",
    "name": "My SaaS",
    "slug": "my-saas",
    "overall_status": "operational",
    "service_count": 5,
    "is_published": true,
    "createdAt": 1709827200000
  }
]

POST/api/v1/stacksAuth Required

Create Stack

Creates a new monitoring stack. Returns the new stack ID.

Parameters

namebodyStack name (required, max 200 chars)

Response

{
  "id": "new_stack_id",
  "slug": "my-saas"
}

PATCH/api/v1/stacks/{id}Auth Required

Update Stack

Update stack settings. All fields are optional.

Parameters

idpathStack ID

namebodyNew stack name

status_page_enabledbodyEnable/disable status page

status_header_textbodyCustom header text for the status page

Response

{ "success": true }

DELETE/api/v1/stacks/{id}Auth Required

Delete Stack

Permanently deletes a stack, all services, status checks, and catalog entries.

Parameters

idpathStack ID

Response

{ "success": true }

POST/api/v1/stacks/{id}/servicesAuth Required

Add Service

Add a service from catalog (provide catalog_service_id) or a custom URL service (provide name + status_page_url).

Parameters

idpathStack ID

catalog_service_idbodyAdd from catalog (mutually exclusive with name/url)

namebodyCustom service name

status_page_urlbodyCustom status page URL

Response

{ "id": "service_id" }

DELETE/api/v1/stacks/{id}/services?service_id=...Auth Required

Remove Service

Remove a service from a stack by its service ID.

Parameters

idpathStack ID

service_idqueryService ID to remove

Response

{ "success": true }

POST/api/v1/stacks/{id}/publishAuth Required

Publish to Catalog

Publishes your stack to the StatusDrop service catalog. Other users can then add your service as a monitored dependency.

Parameters

idpathStack ID

Response

{ "success": true, "catalog_slug": "sd-my-saas" }

DELETE/api/v1/stacks/{id}/publishAuth Required

Unpublish from Catalog

Removes your stack from the service catalog.

Parameters

idpathStack ID

Response

{ "success": true }

Error Responses

All error responses follow this format:

{
  "error": "Human-readable error message"
}

Status	Meaning
401	Invalid or revoked API key (authenticated endpoints only)
403	Plan limit reached or feature not available on current plan
404	Stack not found (invalid or nonexistent stack ID)
429	Rate limit exceeded (120 req/min per IP per stack). Check Retry-After header.
500	Internal server error

Usage Examples

cURL

# Get overall status
curl -s https://statusdrop.dev/api/v1/status/jd74qt7pm0egy36kdtqcx13gm982fb2b | jq .

# Get status history (last 14 days)
curl -s "https://statusdrop.dev/api/v1/status/jd74qt7pm0egy36kdtqcx13gm982fb2b/history?days=14" | jq .

# Export history as CSV
curl -s "https://statusdrop.dev/api/v1/status/jd74qt7pm0egy36kdtqcx13gm982fb2b/history?format=csv" -o history.csv

# Subscribe to RSS feed
curl -s https://statusdrop.dev/api/v1/status/jd74qt7pm0egy36kdtqcx13gm982fb2b/feed

cURL (Authenticated)

# List your stacks
curl -s https://statusdrop.dev/api/v1/stacks \
  -H "Authorization: Bearer sd_live_your_key_here" | jq .

# Create a stack
curl -X POST https://statusdrop.dev/api/v1/stacks \
  -H "Authorization: Bearer sd_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "My SaaS"}'

# Add a service from catalog
curl -X POST https://statusdrop.dev/api/v1/stacks/STACK_ID/services \
  -H "Authorization: Bearer sd_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"catalog_service_id": "CATALOG_ID"}'

# Publish to service catalog
curl -X POST https://statusdrop.dev/api/v1/stacks/STACK_ID/publish \
  -H "Authorization: Bearer sd_live_your_key_here"

JavaScript / TypeScript

const STACK_ID = "jd74qt7pm0egy36kdtqcx13gm982fb2b";

const res = await fetch(`https://statusdrop.dev/api/v1/status/${STACK_ID}`);
const data = await res.json();

console.log(data.overall_status);   // "operational"
console.log(data.status_summary);   // "All 5 third-party services..."

// Check if any service is down
const issues = data.services.filter(s => s.status !== "operational");
if (issues.length > 0) {
  console.warn("Issues detected:", issues.map(s => s.name).join(", "));
}

Python

import requests

STACK_ID = "jd74qt7pm0egy36kdtqcx13gm982fb2b"

resp = requests.get(f"https://statusdrop.dev/api/v1/status/{STACK_ID}")
data = resp.json()

print(data["overall_status"])    # "operational"
print(data["status_summary"])    # "All 5 third-party services..."

for svc in data["services"]:
    print(f"{svc['name']}: {svc['status']}")

# Get history as CSV
csv_resp = requests.get(
    f"https://statusdrop.dev/api/v1/status/{STACK_ID}/history",
    params={"format": "csv", "days": 30}
)
with open("history.csv", "w") as f:
    f.write(csv_resp.text)