API Reference

Opsentry's HTTP API lets you read status, create incidents, and schedule maintenance from your own systems — CI pipelines, on-call runbooks, internal dashboards. Every request is scoped to a single tenant via an API token.

Overview

• Base URL: https://opsentry.io/api/v1 — replace with your own host if self-hosted.
• Content type: requests and responses are JSON (application/json).
• Authentication: bearer token in the Authorization header — see below.
• Versioning: the URL path is versioned (/api/v1/…). Breaking changes go to a new version; existing versions stay supported for at least 12 months after deprecation notice.

Authentication

The API is authenticated with tenant-scoped API tokens. Tokens are bound to a single tenant and a set of scopes that limit what they can do. Sessions (the browser cookie used by the admin UI) cannot be used for API calls — token and session auth are deliberately separate.

Creating tokens

1. Sign in and go to API tokens in the admin sidebar.
2. Click Create token, give it a name (e.g. CI pipeline), pick the scopes it needs, and optionally an expiry.
3. Copy the token immediately. It looks like ops_3f8b… and is shown only once — we store a hash, not the value.
4. Treat it like a password: never commit it to source control, never paste it into shared chat. If a token leaks, revoke it from the same page.

Sending the header

Include the token in the Authorization header on every request:

Authorization: Bearer ops_3f8b1c2d…

Example with curl:

curl https://opsentry.io/api/v1/incidents/active \
  -H "Authorization: Bearer ops_3f8b1c2d…"

JavaScript (fetch):

const res = await fetch("https://opsentry.io/api/v1/incidents/active", {
  headers: { "Authorization": `Bearer ${token}` }
});
const data = await res.json();

Python (requests):

import requests
r = requests.get(
    "https://opsentry.io/api/v1/incidents/active",
    headers={"Authorization": f"Bearer {token}"},
)
data = r.json()

Go:

req, _ := http.NewRequest("GET", "https://opsentry.io/api/v1/incidents/active", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, err := http.DefaultClient.Do(req)

Scopes

Each token carries one or more scopes. The API rejects requests with 403 Forbidden if the token lacks the scope required by the endpoint.

Pick the minimum set the integration needs. A CI pipeline that only declares failed deploys as incidents should hold write:incidents — never read or admin scopes.

Errors

The API uses standard HTTP status codes and returns a JSON body with a short error message:

{
  "error": "missing required scope: write:incidents"
}

Rate limits

The API is rate-limited per token's source IP. Limits are conservative by default; contact support if your integration needs more.

When you hit the limit you get 429 Too Many Requests. Back off and retry — don't tight-loop on 429s.

Endpoints

All paths are relative to https://opsentry.io/api/v1. Responses are JSON. Errors follow the standard shape. Pagination uses limit + offset query parameters where applicable.

Health

Four health endpoints exist, each tuned for a different consumer:

curl -i https://opsentry.io/health

HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: text/plain; charset=utf-8

OK

curl https://opsentry.io/health/live

{
  "status": "ready",
  "checks": {
    "postgres": { "status": "ok", "duration_ms": 2400000 },
    "redis":    { "status": "ok", "duration_ms": 810000 },
    "outbox":   { "status": "ok", "duration_ms": 5100000 }
  }
}

curl https://opsentry.io/api/v1/health \
  -H "Authorization: Bearer ops_3f8b1c2d…"

{
  "ok": true,
  "tenant_id": 17,
  "token_prefix": "3f8b1c2d",
  "scopes": ["read:status", "write:incidents"]
}

Services

curl https://opsentry.io/api/v1/services?status=degraded_performance \
  -H "Authorization: Bearer ops_…"

{
  "services": [{
    "id": 42,
    "slug": "main-api",
    "name": "Main API",
    "current_status": "degraded_performance",
    "visibility": "public",
    "tags": ["prod", "customer-facing"]
  }],
  "total": 1, "limit": 100, "offset": 0
}

{
  "service_id": 42,
  "uptime_24h": 99.97,
  "uptime_7d": 99.94,
  "uptime_30d": 99.91
}

Incidents

curl -X POST https://opsentry.io/api/v1/incidents \
  -H "Authorization: Bearer ops_…" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Deploy failed — rolling back",
    "description": "Health checks failing post-deploy",
    "severity": "degraded",
    "visibility": "public",
    "service_ids": [42]
  }'

curl -X PATCH https://opsentry.io/api/v1/incidents/2041 \
  -H "Authorization: Bearer ops_…" \
  -H "Content-Type: application/json" \
  -d '{"status": "monitoring", "severity": "informational"}'

curl -X POST https://opsentry.io/api/v1/incidents/2041/updates \
  -H "Authorization: Bearer ops_…" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "monitoring",
    "message": "Failover complete. Watching for 15 minutes.",
    "is_public": true
  }'

curl -X POST https://opsentry.io/api/v1/incidents/2041/resolve \
  -H "Authorization: Bearer ops_…" \
  -H "Content-Type: application/json" \
  -d '{
    "root_cause": "Stale DNS cache after failover.",
    "postmortem": "https://internal.notes/inc-2041"
  }'

Maintenance

curl -X POST https://opsentry.io/api/v1/maintenance \
  -H "Authorization: Bearer ops_…" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Database failover drill",
    "description": "Customer Portal will be read-only for ~6 minutes.",
    "scheduled_start": "2026-06-01T02:00:00Z",
    "scheduled_end":   "2026-06-01T04:00:00Z",
    "visibility": "public",
    "service_ids": [17],
    "exclude_from_sla": true,
    "suppress_alerts": true
  }'

curl -X POST https://opsentry.io/api/v1/maintenance/812/start \
  -H "Authorization: Bearer ops_…"

Uptime

Per-service uptime statistics are exposed under /services/:id/uptime (see above) to keep all service-scoped data under a single resource. Tenant-wide rollups are coming.

Changelog

• v1 — health endpoints (load-balancer probe, K8s liveness + readiness, token-verifying ping); services (list/get/uptime); incidents (list/get/create/update/add-update/resolve); maintenance (list/upcoming/get/create/transitions); token auth with three scopes.