A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Opsgenie API is how an app or AI agent works with an Opsgenie account: raising and closing alerts, acknowledging and assigning them, opening incidents, reading who is on call right now, and pinging heartbeats. Access is granted through an API key created on an integration, and that key carries broad access rights, read, create and update, delete, and configuration, rather than a permission per method, so a key can reach a whole area or nothing of it. Opsgenie can also forward events to an app as they happen, set up through an integration.
How an app or AI agent connects to Opsgenie determines what it can reach. Access runs through an API key created on an integration, and the access rights set on that key and integration decide what it can do.
The REST API answers at api.opsgenie.com, or api.eu.opsgenie.com for EU-hosted accounts, under a v2 path segment with a few areas still on v1. It authenticates with a GenieKey API key, and most write actions return 202 Accepted and complete asynchronously.
Integrations are the configured connections that feed events into Opsgenie and forward them out. An inbound integration receives alerts from a monitoring tool, and an outbound one forwards Opsgenie events to another system. The API key an agent uses is itself created on an API integration.
An API key is created on an API integration in Opsgenie and sent in the Authorization header as 'GenieKey
The same API key can be sent using HTTP Basic authentication, as the password with an empty username, base64-encoded. It carries the identical access rights as the GenieKey header, and is offered for clients that send Basic credentials more easily.
The Opsgenie API is split into areas an agent can act on, such as alerts, incidents, on-call schedules, escalations, teams, and heartbeats. Each area has its own methods, and writes here page real people and change who gets notified when something breaks.
Create, read, list, and delete alerts, and acknowledge, close, snooze, escalate, assign, and add notes to them.
Create, read, and list incidents, and close them. Incident endpoints are served under a v1 path segment.
Read, list, and change on-call schedules, and read who is on call now and who is on call next.
Read, list, create, and update escalation chains that decide who is notified next when an alert is not handled.
Read, list, create, and update the teams that own alerts and schedules.
Read, list, create, update, and delete the people in the account.
List integrations, read one, and enable or disable an integration that feeds or forwards events.
Ping a heartbeat to signal a system is alive, list heartbeats, and read one.
List, read, create, and update alert and notification policies that filter and shape alerts.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
AlertsCreate, read, list, and delete alerts, and acknowledge, close, snooze, escalate, assign, and add notes to them.11 | ||||||
| POST | /v2/alerts | Create a new alert. | write | Create and Update | Current | |
Processed asynchronously: returns 202 Accepted with a requestId. Needs the Create and Update access right on the key. Acts onalert Permission (capability) Create and UpdateVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/alerts | List alerts, with filtering, sorting, and offset pagination. | read | Read | Current | |
Falls in the Search rate-limit domain. limit defaults to 20 and maxes at 100. Acts onalert Permission (capability) ReadVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/alerts/count | Count alerts matching a query. | read | Read | Current | |
Returns a count rather than the alerts themselves. Acts onalert Permission (capability) ReadVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/alerts/{identifier} | Get a single alert by id, alias, or tinyId. | read | Read | Current | |
Set identifierType to id, alias, or tiny to choose how the identifier is read. Acts onalert Permission (capability) ReadVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v2/alerts/{identifier} | Delete an alert. | write | Delete | Current | |
Processed asynchronously: returns 202 Accepted with a requestId. Needs the Delete access right on the key. Acts onalert Permission (capability) DeleteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/alerts/{identifier}/acknowledge | Acknowledge an alert. | write | Create and Update | Current | |
Processed asynchronously: returns 202 Accepted with a requestId. Acts onalert Permission (capability) Create and UpdateVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/alerts/{identifier}/close | Close an alert. | write | Create and Update | Current | |
Processed asynchronously: returns 202 Accepted with a requestId. Acts onalert Permission (capability) Create and UpdateVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/alerts/{identifier}/snooze | Snooze an alert until a given time. | write | Create and Update | Current | |
The endTime field sets when the alert wakes again. Processed asynchronously. Acts onalert Permission (capability) Create and UpdateVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/alerts/{identifier}/escalate | Escalate an alert to an escalation chain. | write | Create and Update | Current | |
Routes the alert to the named escalation. Processed asynchronously. Acts onalert Permission (capability) Create and UpdateVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/alerts/{identifier}/assign | Assign an alert to a user. | write | Create and Update | Current | |
The owner field names the user the alert is assigned to. Processed asynchronously. Acts onalert Permission (capability) Create and UpdateVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/alerts/{identifier}/notes | Add a note to an alert. | write | Create and Update | Current | |
Processed asynchronously: returns 202 Accepted with a requestId. Acts onalert Permission (capability) Create and UpdateVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
IncidentsCreate, read, and list incidents, and close them. Incident endpoints are served under a v1 path segment.4 | ||||||
| POST | /v1/incidents/create | Create an incident. | write | Create and Update | Current | |
Incident endpoints are under v1. Processed asynchronously: returns 202 Accepted with a requestId. Acts onincident Permission (capability) Create and UpdateVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/incidents | List incidents, with filtering, sorting, and pagination. | read | Read | Current | |
Incident endpoints are under v1. Acts onincident Permission (capability) ReadVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/incidents/{identifier} | Get a single incident by id or tinyId. | read | Read | Current | |
Incident endpoints are under v1. Acts onincident Permission (capability) ReadVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/incidents/{identifier}/close | Close an incident. | write | Create and Update | Current | |
Incident endpoints are under v1. Processed asynchronously. Acts onincident Permission (capability) Create and UpdateVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Schedules & on-callRead, list, and change on-call schedules, and read who is on call now and who is on call next.4 | ||||||
| GET | /v2/schedules | List on-call schedules. | read | Read | Current | |
Reading the configuration areas needs Configuration Access on the key. Acts onschedule Permission (capability) ReadVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/schedules/{identifier} | Get a single schedule by id or name. | read | Read | Current | |
Set identifierType to id or name. Reading the configuration areas needs Configuration Access. Acts onschedule Permission (capability) ReadVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/schedules/{scheduleIdentifier}/on-calls | Get who is on call now for a schedule. | read | Read | Current | |
Falls in the Schedule-oncalls rate-limit domain. Acts onon-call Permission (capability) ReadVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/schedules/{scheduleIdentifier}/next-on-calls | Get who is on call next for a schedule. | read | Read | Current | |
Falls in the Schedule-oncalls rate-limit domain. Acts onon-call Permission (capability) ReadVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
EscalationsRead, list, create, and update escalation chains that decide who is notified next when an alert is not handled.2 | ||||||
| GET | /v2/escalations | List escalation chains. | read | Read | Current | |
Reading the configuration areas needs Configuration Access on the key. Acts onescalation Permission (capability) ReadVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/escalations | Create an escalation chain. | write | Configuration Access | Current | |
Writing a configuration area needs both Create and Update and Configuration Access on the key. Acts onescalation Permission (capability) Configuration AccessVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
TeamsRead, list, create, and update the teams that own alerts and schedules.2 | ||||||
| GET | /v2/teams | List teams. | read | Read | Current | |
Reading the configuration areas needs Configuration Access on the key. Acts onteam Permission (capability) ReadVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/teams | Create a team. | write | Configuration Access | Current | |
Writing a configuration area needs both Create and Update and Configuration Access on the key. Acts onteam Permission (capability) Configuration AccessVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
UsersRead, list, create, update, and delete the people in the account.3 | ||||||
| GET | /v2/users | List users. | read | Read | Current | |
Falls in the Search rate-limit domain. Reading the configuration areas needs Configuration Access. Acts onuser Permission (capability) ReadVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/users | Create a user. | write | Configuration Access | Current | |
Writing a configuration area needs both Create and Update and Configuration Access on the key. Acts onuser Permission (capability) Configuration AccessVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v2/users/{identifier} | Delete a user. | write | Delete | Current | |
Removing a person needs both Delete and Configuration Access on the key. Acts onuser Permission (capability) DeleteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
IntegrationsList integrations, read one, and enable or disable an integration that feeds or forwards events.2 | ||||||
| GET | /v2/integrations | List integrations, optionally filtered by type or team. | read | Read | Current | |
Reading the configuration areas needs Configuration Access on the key. Acts onintegration Permission (capability) ReadVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/integrations/{id}/enable | Enable an integration. | write | Configuration Access | Current | |
Turning an event source on or off needs both Create and Update and Configuration Access. Acts onintegration Permission (capability) Configuration AccessVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
HeartbeatsPing a heartbeat to signal a system is alive, list heartbeats, and read one.3 | ||||||
| GET | /v2/heartbeats/{name}/ping | Ping a heartbeat to signal a system is alive. | write | — | Current | |
Ping is accepted on GET, POST, PUT, or PATCH. Falls in the Heartbeat rate-limit domain. Acts onheartbeat Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/heartbeats | List heartbeats. | read | Read | Current | |
Reading the configuration areas needs Configuration Access on the key. Acts onheartbeat Permission (capability) ReadVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/heartbeats/{name} | Get a single heartbeat by name. | read | Read | Current | |
Reading the configuration areas needs Configuration Access on the key. Acts onheartbeat Permission (capability) ReadVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
PoliciesList, read, create, and update alert and notification policies that filter and shape alerts.3 | ||||||
| GET | /v2/policies/alert | List global and team-based alert policies. | read | Read | Current | |
Returns at most 1000 policies. Reading the configuration areas needs Configuration Access. Acts onpolicy Permission (capability) ReadVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/policies | Create an alert or notification policy. | write | Configuration Access | Current | |
Writing a configuration area needs both Create and Update and Configuration Access on the key. Acts onpolicy Permission (capability) Configuration AccessVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/policies/{id}/change-order | Change the execution order of a policy. | write | Configuration Access | Current | |
The targetIndex field sets the new position. Needs Create and Update and Configuration Access. Acts onpolicy Permission (capability) Configuration AccessVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Opsgenie can notify an app or AI agent when something happens to an alert, instead of the app repeatedly asking. Outbound notifications are configured as integrations rather than per-event webhook subscriptions through the API, so the events an integration forwards are set up in Opsgenie itself.
| Event | What it signals | Triggered by |
|---|
Opsgenie limits how fast an app or AI agent can call, through a token-bucket model applied separately to each group of endpoints, so heavy alert traffic does not starve configuration calls and the reverse.
Opsgenie uses a token-bucket model where each request spends one token, tracked over both a per-second and a per-minute window. The limits are applied separately to each request domain, such as Alert, Incident, Heartbeat, Configuration (the team, user, escalation, schedule, integration, and policy areas), Search (listing alerts and users), and Schedule-oncalls, so spending one domain's budget does not affect another. Going over returns 429 Too Many Requests, and the response carries X-RateLimit-State (OK, BURST, or THROTTLED), X-RateLimit-Reason (ACCOUNT or INTEGRATION), and X-RateLimit-Period-In-Sec. Atlassian recommends exponential backoff, waiting 2^attemptCount times 200 milliseconds between retries.
List endpoints use offset pagination through the offset parameter, which starts at 0, and the limit parameter, which defaults to 20 and tops out at 100. Results are ordered by the sort field, defaulting to createdAt, and the order parameter, defaulting to desc. List responses also return paging links for the next and previous pages where they apply.
Requests and responses are JSON. Listing endpoints return at most 100 items per page, and the alert policy list returns at most 1000 policies. Individual fields such as an alert message and description have their own length ceilings set per endpoint.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | Bad Request | The request body is not valid, most often invalid JSON. | Correct the request body so it is well-formed JSON and resend. |
| 401 | Unauthenticated | The API key is invalid or the integration it belongs to is disabled. | Check the GenieKey value and the Authorization header, and confirm the integration is enabled and on the right regional host. |
| 402 | Payment Required | The API key is valid, but the account's subscription plan does not allow this action. | Upgrade the plan to one that includes the feature, or avoid the action. |
| 403 | Forbidden | The API key is valid but cannot perform this operation. Code 40301 means the key lacks the access right or permission for it; 40302 means the operation is not supported for this request. | Grant the missing access right on the key, such as Create and Update, Delete, or Configuration Access, or use a key from an API integration. |
| 404 | Not Found | The resource or handler does not exist, or the key's integration cannot see it. | Confirm the identifier and identifierType, and that the integration is scoped to reach the resource. |
| 409 | Conflict | The id or name conflicts with another entity that already exists. | Use a unique name or identifier, or update the existing entity instead. |
| 422 | Unprocessable Entity | The request is well-formed but has semantic errors in the body, such as a field that fails validation. | Read the message field, correct the named field, and resend. |
| 429 | Too Many Requests | A rate limit for the request's domain was exceeded. | Back off using 2^attemptCount times 200 milliseconds, reading the X-RateLimit-State and X-RateLimit-Period-In-Sec headers, before retrying. |
| 500 | Internal Server Error | An unexpected error occurred on Opsgenie's side. | Retry with backoff, and if it persists contact support with the requestId from the response. |
Opsgenie's current REST API is version 2, reached through a v2 path segment, with a few endpoints such as incidents still served under v1. There is no dated version string to pin.
The current REST API is version 2, reached through a v2 path segment, with a few endpoints such as incidents still served under v1. There is no dated version string to pin. Atlassian stopped selling Opsgenie on 4 June 2025, and existing customers can keep using it until end of support on 5 April 2027, after which it shuts down and unmigrated data is deleted. Atlassian directs customers to Jira Service Management for alerting, on-call, and incident management, and to Compass for some operations capabilities.
Before the version 2 REST API, Opsgenie served a version 1 API. Most areas moved to version 2, but some endpoints, such as the incident area, remain under a v1 path segment, so an integration spans both. The older policy area also has a deprecated form that the current policy endpoints replace.
Atlassian has set an end-of-support date for Opsgenie, so an integration built on it should plan to move.
Opsgenie migration and end-of-support notice ↗Bollard AI sits between a team's AI agents and Opsgenie. Grant each agent exactly the access it needs, read or write, area by area, and every call is checked and logged.