Docs menu

API overview

The public endpoints OctoPing offers today, how they are authenticated, their limits and what is not available yet.

Last reviewed

On this page

OctoPing has a small set of public endpoints. They need no account, no session and no key. Everything else you do in OctoPing, such as adding a site or editing a notification, happens in the web app.

Every endpoint on this page is served under one base address.

text
https://octoping.com/api

What exists today

EndpointUse it toReference
GET or POST /ping/{secret_key}Report that a scheduled job ran, so OctoPing can alert when it stops.Heartbeat ping
GET /badges/{webpage_id}.svg and /badges/{webpage_id}/status.svgShow a site's uptime or current status as an image on another page.Badges
GET /status-pages/{slug}/public and /status-pages/{slug}/public/incidentsRead a published status page and its incident history as JSON.Status page JSON

Authentication

These endpoints are public. A heartbeat's secret URL is the only credential among them, and it identifies one heartbeat. A status page shows only what its owner publishes. Every active site has a badge, and anyone who has the site's id can load it (see the note on the badges page). None of these endpoints can add, edit or remove a workspace's sites, heartbeats, notifications or settings.

On the roadmap

API keys for programmatic access are on the roadmap, with no date. Until they exist, no key can authenticate against the API, and reading or changing a workspace's sites, notifications or settings from a script isn't possible. The pricing page lists the roadmap.

Limits and errors

The ping, status page and incident history endpoints are rate limited per address. A caller that sends too many requests gets HTTP 429 with a message in a detail field. Each page in this section lists the other responses its endpoints can return.

Related