HTTP API

Endpoints, authentication and roles.

On this page

The dashboard uses this API, and you can script it too. All endpoints are under /api and take and return JSON.

Not yet stable

The API may change between 0.x releases. Check the changelog when upgrading.

Authentication

Sign in to get a token:

curl -s -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"your-password"}' \
  https://stamon.example.com/api/login
# {"token":"eyJ..."}

Send it as Authorization: Bearer <token>. Signing in also sets a token cookie, which the dashboard uses. Tokens last 60 minutes; sign in again for a new one.

Each request is checked against the user's current role, so role changes and deactivation apply right away.

StatusMeaning
401Missing or invalid token
403The user's role is too low, or the account is deactivated

Endpoints

The Role column is the minimum role needed.

Account

MethodPathRoleNotes
GET/api/checkPublic200 once an account exists, 404 before
POST/api/registerPublic{username, password, timezone?}; only works while there are no users, and creates the admin
POST/api/loginPublic{username, password} → {token}
GET/api/logoutPublicClears the cookie
GET/api/userViewerThe signed-in user
GET/api/usersViewerAll users
POST/api/usersAdmin{username, password, role?, timezone?}; role defaults to viewer
PUT/api/users/{id}Admin{role?, active?}; not for your own account

Services

MethodPathRoleNotes
GET/api/servicesViewerAll services, with secrets hidden
POST/api/servicesEditorSee Service body
GET/api/services/{id}ViewerOne service
PUT/api/services/{id}EditorAny service fields to change
DELETE/api/services/{id}Editor
GET/api/services/{id}/logs?limit=100ViewerRecent check results
GET/api/services/{id}/statsViewerUptime and latency over 24 hours, 7 days and 30 days
GET/api/services/{id}/channelsViewer{channel_ids} linked to the service
PUT/api/services/{id}/channelsEditor{channel_ids}
GET/api/statsViewerCounts of services up, down and failed
GET/api/logs?limit=100ViewerRecent check results for all services
GET/api/logs/incidents?limit=20ViewerRecent incidents

Alerts, maintenance and status pages

MethodPathRoleNotes
GET/api/channelsViewerChannels, without their settings
POST/api/channelsAdmin{name, active?, apply_to_all?, config}
GET/api/channels/{id}AdminIncludes settings and credentials
PUT/api/channels/{id}AdminAny channel fields to change
DELETE/api/channels/{id}Admin
POST/api/channels/{id}/testAdminSends a test alert; 502 with the error if it fails
GET/api/notifications?limit=50ViewerAlert history
GET/api/maintenanceViewerMaintenance windows
POST/api/maintenanceEditor{title, description?, starts_at, ends_at, apply_to_all?, service_ids?}; times in RFC 3339
PUT, DELETE/api/maintenance/{id}Editor
GET/api/status-pagesViewerStatus pages
POST/api/status-pagesEditor{slug, title, description?, published?, service_ids?}; slugs use lowercase letters, digits and dashes
PUT, DELETE/api/status-pages/{id}Editor
GET/api/status/{slug}PublicA published status page's data
GET, POST/api/push/{token}PublicPush heartbeat

Service body 

{
  "name": "Website",
  "interval": 60,
  "timeout": 10,
  "retry": 2,
  "retry_interval": 20,
  "invert": false,
  "active": true,
  "tags": ["production"],
  "channel_ids": [1],
  "config": { "type": "http", "url": "https://example.com" }
}

config.type selects the check type, and the other config fields are that type's settings. Times are in seconds. timeout defaults to 10, active to true and invert to false.

Statuses

Check results report status as a number:

ValueStatus
0Pending (retrying)
1Up
2Down
3Failed (the check itself errored)
4Maintenance

Live updates

/ws (outside /api) is a WebSocket that sends every new check result and dashboard notification as JSON:

{"type":"log","value":{"service_id":1,"status":1,"message":null,"time":"…","duration":42}}
{"type":"notification","value":{"title":"Service Down","message":"…","level":"error"}}