Getting started · Integrations · API
API
Everything in the app is also a JSON API. For agents, use the MCP server instead: seeAI & MCP.
REST: https://shift.nightroll.app/api/v1
Create an API key in Settings → API keys and send it asAuthorization: Bearer $KEY. The key belongs to one org and carries scopes: read for GETs,write for changes, admin for the phone provider, chat webhooks and alert archives. Role is your role in the org (viewer, member, admin, owner); a key never has more access than the person who made it.
curl https://shift.nightroll.app/api/v1/oncall -H "Authorization: Bearer $KEY"| Method | Path | Role | What |
|---|---|---|---|
| GET | /alerts?all=1&q= | viewer | Open alerts; all=1 adds the latest resolved (100 at most), q searches. Resolved alerts older than 30 days are archived and not here |
| GET | /alerts/:id | viewer | {alert, log} with the timeline |
| GET | /alerts/archives | admin | Archived days, newest first: {days: [{day, rows, where: bucket | nightroll}]}, rows = alerts |
| GET | /alerts/archives/:day | admin | That day's file (gzipped JSON lines, one alert with its timeline per line), YYYY-MM-DD as listed |
| POST | /alerts | member | {service_id, title, severity?} opens an alert, or {user_id, message} pages one person. Over an API key or OAuth: 5 an hour per org |
| POST | /alerts/:id | member | {action: acknowledge | resolve | unacknowledge | reassign | note, to?, text?} |
| POST | /alerts/:id/summary | member | Summarize on your own AI key; adds the summary as a note |
| GET | /services | viewer | Services with their keys and settings |
| POST | /services | member | {name} creates a service and its first key → {id} |
| PUT | /services/:id | member | Any of {name, policy_id, urgency, ack_timeout_min, auto_resolve_min, mapping} |
| DELETE | /services/:id | member | Removes the service |
| POST | /services/:id/keys | member | A new integration key → {key} |
| DELETE | /keys/:key | member | Revokes an integration key |
| GET PUT | /services/:id/chat | admin | Chat webhooks (slack, teams, discord, mattermost, telegram, ntfy); GET shows hosts only |
| GET POST | /policies | viewer / member | Escalation policies: 1 to 20 levels of {timeout_min, targets, round_robin}, repeat up to 9 |
| PUT DELETE | /policies/:id | member | Update or delete a policy |
| GET POST | /schedules | viewer / member | Schedules with who is on call now and the next shifts; create one |
| PUT DELETE | /schedules/:id | member | Update or delete a schedule |
| GET | /schedules/:id/roster?days= | viewer | Who is on call, shift by shift, for 1 to 60 days |
| POST | /schedules/:id/overrides | member | {user_id, start, end} (ms or ISO 8601), 90 days at most |
| DELETE | /schedules/:id/overrides/:oid | member | Removes an override |
| GET | /oncall | viewer | Who is on call now on each schedule, and until when |
| GET POST | /me/contacts | any | Your contact methods (push, email, sms, voice); DELETE /me/contacts/:id removes one |
| GET PUT | /me/rules | any | Your paging rules for high and low urgency, and handoff hours |
| POST | /me/test-page | member | Sends you a test page |
| GET PUT | /telephony | admin | Your Twilio or Telnyx account; GET shows provider, From number and the last 4 of the credential |
Members, invites, API keys, usage and the audit log are the platform's endpoints under/api/orgs/:org/…; the matching MCP tools are listed on AI & MCP.
Alerts in: https://shift.nightroll.app
These paths take a service's integration key instead of an API key, and answer in the shape of the API they copy. See Integrations for each tool.
| Method | Path | What |
|---|---|---|
| POST | /v2/enqueue | PagerDuty Events API v2 (routing_key in the body) |
| POST | /generic/2010-04-15/create_event.json | PagerDuty Events API v1 (service_key in the body) |
| POST | /v2/change/enqueue | Change events: accepted (202), not stored |
| POST | /i/KEY | Alertmanager, Grafana, presets or any webhook |
| POST | /v2/alerts | Opsgenie: create (Authorization: GenieKey KEY) |
| GET | /v2/alerts, /v2/alerts/:id | Opsgenie: list and get |
| POST | /v2/alerts/:id/close | acknowledge | unacknowledge | notes | Opsgenie: actions |
| PUT | /v2/alerts/:id/message | description | Opsgenie: edit |
| GET | /v2/alerts/requests/:id | Opsgenie: request status |