# On-Call API

Version 1.0 · OpenAPI 3.1.0

The On-Call API: alerts, incidents, schedules, escalation policies,
integrations, maintenance windows and the settings around them. It is the API
the EvoHub console itself uses.

**Authentication.** Send an API key as `Authorization: Bearer evohub_…` or
`X-API-Key: evohub_…`. A key works in one organization. See *API keys and
scopes* and *Errors* in these docs.

**Permissions.** Each operation names the permission it needs
(`x-evohub-permission`); an API key needs it among its scopes. A key is
always held to its scopes, even one made by an administrator. A role that still
holds the older `oncall:read` or `oncall:write` permission passes the matching
`oncall:<resource>:read` or `:write` checks (not `oncall:alert:respond`). A
refusal is **403 `FORBIDDEN`**, never 401.

**Teams.** Schedules, escalation policies and integrations can belong to a
team. Those are visible only to callers in that team; others get 404, as if
they did not exist. An organization key scoped to a team sees that team's
items and the organization-wide ones; an organization key without a team sees
the organization-wide ones. A personal key acts as its owner and sees what
they see: the organization-wide items and those of the owner's teams.

**Responses.** Success is `{"data": …, "success": true}`; paged alert lists
add `meta.total`. Errors are `{"error": {"code", "message"}}`, plus `details`
for `VALIDATION_FAILED`. Times are RFC 3339 in UTC. Ids are opaque strings.

**Not here.** Sending alerts into EvoHub from a monitoring tool uses an
integration key, not an API key: see the *Alert ingest API* reference.

## Servers

- `https://evohub.io`

## Authentication

- `bearerAuth`: HTTP Bearer — An EvoHub API key (`evohub_…`) as a bearer token.
- `apiKeyHeader`: API key in the header `X-API-Key` — An EvoHub API key (`evohub_…`).

## Alerts

The paged objects: list, raise and answer alerts.

- [GET /api/v1/alerts](https://docs-dev.evohub.io/oncall/list-alerts.md): List alerts
- [POST /api/v1/alerts](https://docs-dev.evohub.io/oncall/create-alert.md): Raise an alert
- [GET /api/v1/alerts/{id}](https://docs-dev.evohub.io/oncall/get-alert.md): Get an alert
- [GET /api/v1/alerts/{id}/events](https://docs-dev.evohub.io/oncall/list-alert-events.md): List an alert's timeline
- [POST /api/v1/alerts/{id}/events](https://docs-dev.evohub.io/oncall/add-alert-note.md): Add a note to an alert
- [POST /api/v1/alerts/{id}/acknowledge](https://docs-dev.evohub.io/oncall/acknowledge-alert.md): Acknowledge an alert
- [POST /api/v1/alerts/{id}/resolve](https://docs-dev.evohub.io/oncall/resolve-alert.md): Resolve an alert
- [POST /api/v1/alerts/{id}/suppress](https://docs-dev.evohub.io/oncall/suppress-alert.md): Suppress an alert
- [POST /api/v1/alerts/{id}/assign](https://docs-dev.evohub.io/oncall/assign-alert.md): Assign an alert
- [POST /api/v1/alerts/{id}/takeover](https://docs-dev.evohub.io/oncall/take-over-alert.md): Take over an alert
- [POST /api/v1/alerts/{id}/redirect](https://docs-dev.evohub.io/oncall/redirect-alert.md): Redirect an alert to another policy
- [POST /api/v1/alerts/acknowledge-bulk](https://docs-dev.evohub.io/oncall/acknowledge-alerts-bulk.md): Acknowledge several alerts
- [POST /api/v1/alerts/resolve-bulk](https://docs-dev.evohub.io/oncall/resolve-alerts-bulk.md): Resolve several alerts
- [POST /api/v1/alerts/takeover-bulk](https://docs-dev.evohub.io/oncall/take-over-alerts-bulk.md): Take over several alerts
- [POST /api/v1/alerts/resolve-by-fingerprint](https://docs-dev.evohub.io/oncall/resolve-alert-by-fingerprint.md): Resolve an alert by fingerprint
- [GET /api/v1/alerts/stats](https://docs-dev.evohub.io/oncall/get-alert-stats.md): Count alerts by status
- [GET /api/v1/alerts/fields](https://docs-dev.evohub.io/oncall/list-alert-fields.md): List alert field names
- [GET /api/v1/alerts/sse](https://docs-dev.evohub.io/oncall/stream-alerts.md): Stream alert changes

## Incidents

Human-declared incidents and their timelines.

- [GET /api/v1/incidents](https://docs-dev.evohub.io/oncall/list-incidents.md): List incidents
- [POST /api/v1/incidents](https://docs-dev.evohub.io/oncall/create-incident.md): Declare an incident
- [GET /api/v1/incidents/{id}](https://docs-dev.evohub.io/oncall/get-incident.md): Get an incident
- [PUT /api/v1/incidents/{id}](https://docs-dev.evohub.io/oncall/update-incident.md): Update an incident
- [POST /api/v1/incidents/{id}/acknowledge](https://docs-dev.evohub.io/oncall/acknowledge-incident.md): Mark an incident identified
- [POST /api/v1/incidents/{id}/resolve](https://docs-dev.evohub.io/oncall/resolve-incident.md): Resolve an incident
- [GET /api/v1/incidents/{id}/timeline](https://docs-dev.evohub.io/oncall/list-incident-timeline.md): List an incident's timeline
- [POST /api/v1/incidents/{id}/timeline](https://docs-dev.evohub.io/oncall/add-incident-timeline-entry.md): Add a timeline entry
- [DELETE /api/v1/incidents/{id}/timeline/{entryID}](https://docs-dev.evohub.io/oncall/delete-incident-timeline-entry.md): Delete a timeline entry
- [PATCH /api/v1/incidents/{id}/timeline/{entryID}](https://docs-dev.evohub.io/oncall/edit-incident-timeline-entry.md): Edit a timeline entry
- [GET /api/v1/incidents/{id}/sse](https://docs-dev.evohub.io/oncall/stream-incident-timeline.md): Stream an incident's timeline

## Status page publishing

Publish an incident to one of your status pages.

- [GET /api/v1/incidents/{id}/publish](https://docs-dev.evohub.io/oncall/get-incident-publication.md): Get publishing state
- [POST /api/v1/incidents/{id}/publish](https://docs-dev.evohub.io/oncall/publish-incident.md): Publish to a status page
- [DELETE /api/v1/incidents/{id}/publish](https://docs-dev.evohub.io/oncall/unpublish-incident.md): Remove from the status page

## Postmortems

Post-incident reviews.

- [GET /api/v1/incidents/{id}/postmortem](https://docs-dev.evohub.io/oncall/get-postmortem.md): Get an incident's postmortem
- [PUT /api/v1/incidents/{id}/postmortem](https://docs-dev.evohub.io/oncall/replace-postmortem.md): Write an incident's postmortem (PUT)
- [POST /api/v1/incidents/{id}/postmortem](https://docs-dev.evohub.io/oncall/save-postmortem.md): Write an incident's postmortem

## Schedules

On-call schedules and who is on call.

- [GET /api/v1/schedules](https://docs-dev.evohub.io/oncall/list-schedules.md): List schedules
- [POST /api/v1/schedules](https://docs-dev.evohub.io/oncall/create-schedule.md): Create a schedule
- [GET /api/v1/schedules/{id}](https://docs-dev.evohub.io/oncall/get-schedule.md): Get a schedule
- [PUT /api/v1/schedules/{id}](https://docs-dev.evohub.io/oncall/update-schedule.md): Update a schedule
- [DELETE /api/v1/schedules/{id}](https://docs-dev.evohub.io/oncall/delete-schedule.md): Delete a schedule
- [GET /api/v1/schedules/{id}/on-call-now](https://docs-dev.evohub.io/oncall/get-schedule-on-call-now.md): Who is on call on a schedule
- [GET /api/v1/on-call-now](https://docs-dev.evohub.io/oncall/list-on-call-now.md): Who is on call everywhere
- [GET /api/v1/schedules/my-on-call](https://docs-dev.evohub.io/oncall/get-my-on-call.md): My on-call shifts

## Schedule layers

Rotation layers and the people in them.

- [POST /api/v1/schedules/{id}/layers](https://docs-dev.evohub.io/oncall/create-schedule-layer.md): Add a layer
- [DELETE /api/v1/schedules/{id}/layers/{layerID}](https://docs-dev.evohub.io/oncall/delete-schedule-layer.md): Delete a layer
- [PATCH /api/v1/schedules/{id}/layers/{layerID}](https://docs-dev.evohub.io/oncall/update-schedule-layer.md): Update a layer
- [PUT /api/v1/schedules/{id}/layers/{layerID}/rotations](https://docs-dev.evohub.io/oncall/reorder-schedule-rotations.md): Reorder a layer's rota
- [POST /api/v1/schedules/{id}/layers/{layerID}/rotations](https://docs-dev.evohub.io/oncall/add-schedule-rotation.md): Add a person to a layer
- [DELETE /api/v1/schedules/{id}/layers/{layerID}/rotations/{rotationID}](https://docs-dev.evohub.io/oncall/delete-schedule-rotation.md): Remove a person from a layer

## Overrides

Temporary cover on a schedule.

- [GET /api/v1/schedules/{id}/overrides](https://docs-dev.evohub.io/oncall/list-schedule-overrides.md): List overrides
- [POST /api/v1/schedules/{id}/overrides](https://docs-dev.evohub.io/oncall/create-schedule-override.md): Create an override
- [DELETE /api/v1/schedules/{id}/overrides/{overrideID}](https://docs-dev.evohub.io/oncall/delete-schedule-override.md): Delete an override

## Escalation policies

Who is notified about an alert, in what order.

- [GET /api/v1/escalation-policies](https://docs-dev.evohub.io/oncall/list-escalation-policies.md): List escalation policies
- [POST /api/v1/escalation-policies](https://docs-dev.evohub.io/oncall/create-escalation-policy.md): Create an escalation policy
- [GET /api/v1/escalation-policies/{id}](https://docs-dev.evohub.io/oncall/get-escalation-policy.md): Get an escalation policy
- [PUT /api/v1/escalation-policies/{id}](https://docs-dev.evohub.io/oncall/update-escalation-policy.md): Update an escalation policy
- [DELETE /api/v1/escalation-policies/{id}](https://docs-dev.evohub.io/oncall/delete-escalation-policy.md): Delete an escalation policy

## Integrations

Monitoring tools that send alerts, and their keys.

- [GET /api/v1/integrations](https://docs-dev.evohub.io/oncall/list-integrations.md): List integrations
- [POST /api/v1/integrations](https://docs-dev.evohub.io/oncall/create-integration.md): Create an integration
- [GET /api/v1/integrations/{id}](https://docs-dev.evohub.io/oncall/get-integration.md): Get an integration
- [PUT /api/v1/integrations/{id}](https://docs-dev.evohub.io/oncall/update-integration.md): Update an integration
- [DELETE /api/v1/integrations/{id}](https://docs-dev.evohub.io/oncall/delete-integration.md): Delete an integration
- [PUT /api/v1/integrations/{id}/signing-secret](https://docs-dev.evohub.io/oncall/set-integration-signing-secret.md): Set or generate a signing secret
- [DELETE /api/v1/integrations/{id}/signing-secret](https://docs-dev.evohub.io/oncall/clear-integration-signing-secret.md): Remove a signing secret

## Maintenance windows

Planned work that holds back paging.

- [GET /api/v1/maintenance-windows](https://docs-dev.evohub.io/oncall/list-maintenance-windows.md): List maintenance windows
- [POST /api/v1/maintenance-windows](https://docs-dev.evohub.io/oncall/create-maintenance-window.md): Schedule a maintenance window
- [GET /api/v1/maintenance-windows/{id}](https://docs-dev.evohub.io/oncall/get-maintenance-window.md): Get a maintenance window
- [DELETE /api/v1/maintenance-windows/{id}](https://docs-dev.evohub.io/oncall/delete-maintenance-window.md): Delete a maintenance window
- [PATCH /api/v1/maintenance-windows/{id}](https://docs-dev.evohub.io/oncall/update-maintenance-window.md): Update a maintenance window
- [POST /api/v1/maintenance-windows/{id}/complete](https://docs-dev.evohub.io/oncall/complete-maintenance-window.md): End a maintenance window now
- [GET /api/v1/maintenance-windows/{id}/updates](https://docs-dev.evohub.io/oncall/list-maintenance-updates.md): List a window's updates
- [POST /api/v1/maintenance-windows/{id}/updates](https://docs-dev.evohub.io/oncall/add-maintenance-update.md): Post an update
- [DELETE /api/v1/maintenance-windows/{id}/updates/{updateID}](https://docs-dev.evohub.io/oncall/delete-maintenance-update.md): Delete an update
- [PATCH /api/v1/maintenance-windows/{id}/updates/{updateID}](https://docs-dev.evohub.io/oncall/edit-maintenance-update.md): Edit an update

## Analytics

MTTA, MTTR, noise and load.

- [GET /api/v1/alerts/analytics](https://docs-dev.evohub.io/oncall/get-alert-analytics.md): Alert analytics
- [GET /api/v1/incidents/analytics](https://docs-dev.evohub.io/oncall/get-incident-analytics.md): Incident analytics

## Message templates

Default status-update texts and the voice-call template.

- [GET /api/v1/update-templates](https://docs-dev.evohub.io/oncall/list-update-templates.md): List status-update templates
- [PUT /api/v1/update-templates](https://docs-dev.evohub.io/oncall/save-update-template.md): Save a status-update template
- [GET /api/v1/voice-template](https://docs-dev.evohub.io/oncall/get-voice-template.md): Get the voice-call template
- [PUT /api/v1/voice-template](https://docs-dev.evohub.io/oncall/save-voice-template.md): Save the voice-call template
- [POST /api/v1/voice-template/preview](https://docs-dev.evohub.io/oncall/preview-voice-template.md): Preview a voice-call template

## My notifications

How and when the caller is notified.

- [GET /api/v1/notification-preferences](https://docs-dev.evohub.io/oncall/list-notification-preferences.md): List my notification methods
- [POST /api/v1/notification-preferences](https://docs-dev.evohub.io/oncall/create-notification-preference.md): Add a notification method
- [PUT /api/v1/notification-preferences/{id}](https://docs-dev.evohub.io/oncall/update-notification-preference.md): Update a notification method
- [DELETE /api/v1/notification-preferences/{id}](https://docs-dev.evohub.io/oncall/delete-notification-preference.md): Remove a notification method
- [PATCH /api/v1/notification-preferences/{id}](https://docs-dev.evohub.io/oncall/update-notification-preference-partial.md): Update a notification method (PATCH)
- [GET /api/v1/notification-schedule](https://docs-dev.evohub.io/oncall/get-notification-schedule.md): Get my notification schedule
- [PUT /api/v1/notification-schedule](https://docs-dev.evohub.io/oncall/save-notification-schedule.md): Save my notification schedule

## Slack

The organization's Slack workspace.

- [GET /api/v1/slack](https://docs-dev.evohub.io/oncall/get-slack-connection.md): Get the Slack connection
- [DELETE /api/v1/slack](https://docs-dev.evohub.io/oncall/disconnect-slack.md): Disconnect Slack
- [POST /api/v1/slack/install](https://docs-dev.evohub.io/oncall/start-slack-install.md): Start connecting Slack
- [GET /api/v1/slack/channels](https://docs-dev.evohub.io/oncall/list-slack-channels.md): List Slack channels
- [PUT /api/v1/slack/default-channel](https://docs-dev.evohub.io/oncall/set-slack-default-channel.md): Set the default Slack channel

## Microsoft Teams

Teams channels and the action links on Teams cards.

- [GET /api/v1/chat](https://docs-dev.evohub.io/oncall/get-chat-status.md): Get chat availability
- [GET /api/v1/chat/channels](https://docs-dev.evohub.io/oncall/list-chat-channels.md): List Teams channels
- [POST /api/v1/chat/channels](https://docs-dev.evohub.io/oncall/create-chat-channel.md): Add a Teams channel
- [DELETE /api/v1/chat/channels/{id}](https://docs-dev.evohub.io/oncall/delete-chat-channel.md): Remove a Teams channel
- [PATCH /api/v1/chat/channels/{id}](https://docs-dev.evohub.io/oncall/update-chat-channel.md): Update a Teams channel
- [POST /api/v1/chat/channels/{id}/test](https://docs-dev.evohub.io/oncall/test-chat-channel.md): Send a test message
- [GET /api/v1/chat/actions/{token}](https://docs-dev.evohub.io/oncall/preview-chat-action.md): Preview a Teams action link
- [POST /api/v1/chat/actions/{token}](https://docs-dev.evohub.io/oncall/run-chat-action.md): Run a Teams action link

## Import

Bring schedules, policies and integrations over from Opsgenie or PagerDuty.

- [POST /api/v1/import/opsgenie/preview](https://docs-dev.evohub.io/oncall/preview-opsgenie-import.md): Preview an import from Opsgenie
- [POST /api/v1/import/opsgenie/apply](https://docs-dev.evohub.io/oncall/apply-opsgenie-import.md): Import from Opsgenie
- [POST /api/v1/import/pagerduty/preview](https://docs-dev.evohub.io/oncall/preview-pager-duty-import.md): Preview an import from PagerDuty
- [POST /api/v1/import/pagerduty/apply](https://docs-dev.evohub.io/oncall/apply-pager-duty-import.md): Import from PagerDuty

## Audit log

Who changed what in On-Call.

- [GET /api/v1/oncall-audit-logs](https://docs-dev.evohub.io/oncall/list-oncall-audit-logs.md): List the On-Call audit log