Cross-posted from the Fluidify blog.

The Opsgenie API is how most teams send alerts from scripts, CI pipelines, and custom monitors, and how they back up or automate configuration. This guide covers the Opsgenie REST API in practice: which Opsgenie API key to use for what, where the docs live now, how to create, acknowledge, and close alerts with curl, the rate limits you'll hit, and what to change in that code before Opsgenie shuts down on April 5, 2027.

Key takeaways

  • Opsgenie has two kinds of API keys. Integration API keys (from an API integration) can create, acknowledge, and close alerts. Account-level keys from API Key Management are for configuration and reading, and they can't create or close alerts.
  • Every request uses the header Authorization: GenieKey <key> against https://api.opsgenie.com, or https://api.eu.opsgenie.com for EU accounts.
  • Creating an alert is asynchronous. POST /v2/alerts returns 202 with a requestId, and you check the result at GET /v2/alerts/requests/:requestId. Use alias for deduplication and to close the alert later.

Where the Opsgenie API docs live

The REST API reference is still at docs.opsgenie.com, organized by domain: Alert, Incident, Heartbeat, Schedule, Escalation, Team, User, Integration, and so on. Many of the conceptual pages, including API key management, have moved to Atlassian's support site under support.atlassian.com/opsgenie, and old docs.opsgenie.com links redirect there. The current API is version 2, and endpoint paths start with /v2/.

Opsgenie API key types

Getting the key type wrong is the most common reason a request returns 403 or silently can't do what you want.

Key type Where you create it Can create, ack, close alerts Can read and change configuration
Team API integration key A team's integrations Yes, for that team's alerts No
Global API integration key Account-level integrations Yes Yes
API Key Management key Settings > App Settings > API Key Management No Yes, depending on access rights

Integration API keys: you get one by adding an API integration in Opsgenie. Atlassian's docs say a team integration's key only works for that team's alerts and incidents, while a global integration's key can be used for all API requests, including account configuration. Use an integration key in anything that sends alerts.

API Key Management keys: these are account-level keys not tied to any integration. Account owners and admins create them under Settings > App Settings > API Key Management by choosing Add New API Key, naming it, and picking access rights. Atlassian says they can read alerts (Get Alert, List Alerts) and work with incidents, but Create Alert, Acknowledge Alert, Close Alert, and Add Note to Alert are blocked. Atlassian also says API Key Management is available on every subscription plan.

The access rights for an API Key Management key are:

  • Read: read alerts, incidents, and configuration.
  • Create and Update: create and update configuration and incidents.
  • Delete: delete alerts, incidents, and configuration.
  • Configuration Access: without it, the key can only reach alert and incident data.

For backups or a migration export, Atlassian's guidance is to grant all access rights. For a key that only exports schedules, Read plus Configuration Access is enough.

Authenticating requests

Every call sends the key in the Authorization header with the GenieKey prefix:

curl -s "https://api.opsgenie.com/v2/alerts?limit=5" \ -H "Authorization: GenieKey $OPSGENIE_API_KEY" 

EU accounts must use https://api.eu.opsgenie.com. Opsgenie's docs say requests to the wrong region fail, which is an easy mistake to make when copying examples.

Creating an alert with the Opsgenie API

The Opsgenie create alert API is POST /v2/alerts. Only message is required:

curl -s -X POST "https://api.opsgenie.com/v2/alerts" \ -H "Content-Type: application/json" \ -H "Authorization: GenieKey $OPSGENIE_API_KEY" \ -d '{ "message": "Checkout API error rate above 5%", "alias": "checkout-api-error-rate", "description": "5xx rate on checkout-api has been above 5% for 10 minutes.", "responders": [{"name": "Payments", "type": "team"}], "tags": ["checkout", "production"], "details": {"service": "checkout-api", "region": "us-east-1"}, "entity": "checkout-api", "source": "ci-smoke-tests", "priority": "P1" }' 

The fields you'll use most, with the limits from the Alert API reference:

Field Limit Notes
message 130 characters Required. The alert title
alias 512 characters Deduplication key. Reuse it to update or close the alert
description 15,000 characters Longer context
responders 50 items Teams, users, escalations, or schedules, by id or name
visibleTo 50 items Teams or users who can see the alert
actions 10 items, 50 characters each Custom action buttons
tags 20 items, 50 characters each Free-form labels
details 8,000 characters total Key-value map of extra properties
entity 512 characters The affected thing, like a host or service
source 100 characters Defaults to the request's IP address
priority P1 to P5 Defaults to P3
note 25,000 characters Added to the alert when it's created

The response is HTTP 202 Accepted with a requestId, because Opsgenie processes alert requests asynchronously. A 202 means the request was accepted, not that the alert exists. If your script needs to confirm it, poll the request status:

curl -s "https://api.opsgenie.com/v2/alerts/requests/$REQUEST_ID" \ -H "Authorization: GenieKey $OPSGENIE_API_KEY" 

Deduplicating with alias

If an open alert already has the same alias, Opsgenie treats a new create request as a duplicate of it instead of opening a second alert. Pick an alias that identifies the problem, not the occurrence: checkout-api-error-rate is good, a timestamp is not. A stable alias is also what lets you acknowledge and close the alert later without storing Opsgenie's alert ID.

Acknowledging and closing alerts

Both endpoints take the alert's identifier, and identifierType tells Opsgenie whether it's the id, the tiny ID, or the alias:

# Acknowledge by alias curl -s -X POST "https://api.opsgenie.com/v2/alerts/checkout-api-error-rate/acknowledge?identifierType=alias" \ -H "Content-Type: application/json" \ -H "Authorization: GenieKey $OPSGENIE_API_KEY" \ -d '{"user": "deploy-bot", "source": "ci", "note": "Rollback in progress"}' # Close by alias curl -s -X POST "https://api.opsgenie.com/v2/alerts/checkout-api-error-rate/close?identifierType=alias" \ -H "Content-Type: application/json" \ -H "Authorization: GenieKey $OPSGENIE_API_KEY" \ -d '{"user": "deploy-bot", "source": "ci", "note": "Error rate back under 1%"}' 

The body is optional, with user, source, and note. Both calls are asynchronous and return 202, the same as create. The usual pattern for a monitor is to create with an alias when a check fails and close by the same alias when it recovers.

Opsgenie API rate limits

Opsgenie rate-limits by domain (Alert, Configuration, Incident, Heartbeat, Schedule on-calls, and others), with separate per-minute and per-second limits for each. The actual numbers depend on your plan and user count, and Opsgenie shows yours under Reports > API Usage. The rate limiting docs give an example of a Standard plan with 60 users reaching 740 requests per minute and 101 per second on one domain, with a fairness rule that caps any single integration at 10% of that.

When you exceed a limit, Opsgenie returns 429 Too Many Requests. Some REST requests over the threshold are delayed by five seconds instead of rejected. Three headers tell you what happened:

  • X-RateLimit-State: OK, BURST (accepted but delayed), or THROTTLED (rejected).
  • X-RateLimit-Reason: ACCOUNT or INTEGRATION, when a request is delayed or rejected.
  • X-RateLimit-Period-In-Sec: 60 or 1, telling you whether the per-minute or per-second limit was hit.

Retry 429s with exponential backoff. Bulk exports during a migration are the most likely time to hit these, so spread schedule and configuration exports out rather than firing them in parallel.

Other useful Opsgenie API endpoints

  • Schedules: GET /v2/schedules, GET /v2/schedules/:identifier/timeline, and GET /v2/schedules/:identifier.ics for exports. Our schedule export guide covers them in detail.
  • Escalations, teams, users, and integrations: the Configuration domain, useful for backups and for rebuilding setup in another tool.
  • Who is on call: a separate API under the Schedule domain for looking up current on-call responders.

If you manage Opsgenie with Terraform rather than direct API calls, the provider uses the same keys: Opsgenie's provider docs say to create an API integration with read and write permissions. Our Opsgenie reference guide covers the Terraform provider.

Before the shutdown: find every Opsgenie API call

On April 5, 2027 every one of these calls stops working. Inventory them now:

  1. Search your repositories, CI configuration, and serverless functions for api.opsgenie.com, api.eu.opsgenie.com, and GenieKey.
  2. List every API integration and API Key Management key in Opsgenie, and which system uses each.
  3. Check monitoring tools that send to Opsgenie through a built-in integration rather than your own code. Those need a new destination too.
  4. Note anything that depends on Opsgenie-specific behavior, like aliases for deduplication or the asynchronous request ID.

Then map each call to the destination tool's equivalent. The concepts carry across most alerting APIs: a title, a severity, a deduplication key, labels, and a way to resolve. The full migration sequence is in our Opsgenie migration checklist.

Mapping Opsgenie create-alert calls to FluidifyAI Regen

If you're moving to FluidifyAI Regen, its generic webhook accepts a batch of alerts at a per-workspace URL, POST /api/v1/webhooks/generic/<routing_token>, which you copy from the Integrations page. Only title is required. Here's how an Opsgenie create-alert payload maps over:

Opsgenie field Regen generic webhook field
message title
description description
alias external_id
priority (P1 to P5) severity (critical, warning, or info)
tags and details labels
entity, source labels or source
close request same external_id with status resolved

Opsgenie has five priorities and Regen's generic webhook has three severities, so choose a mapping and apply it consistently. One reasonable choice is P1 and P2 to critical, P3 to warning, and P4 and P5 to info. The Opsgenie alert above becomes:

curl -s -X POST "<your generic webhook URL from the Integrations page>" \ -H "Content-Type: application/json" \ -d '{ "alerts": [{ "title": "Checkout API error rate above 5%", "description": "5xx rate on checkout-api has been above 5% for 10 minutes.", "severity": "critical", "status": "firing", "external_id": "checkout-api-error-rate", "labels": {"service": "checkout-api", "region": "us-east-1", "env": "production"} }] }' 

Sending the same external_id again updates the existing alert instead of creating a new one, the same job alias does in Opsgenie. To close it, send the same payload with "status": "resolved". You can require an HMAC-SHA256 signature on these requests by setting a webhook secret, which the generic webhook docs explain. If your alerts come from Prometheus Alertmanager, Grafana, or CloudWatch, Regen has dedicated endpoints for those, so you don't need to translate payloads at all.

FAQ

How do I get an Opsgenie API key? To send alerts, add an API integration (account-level or under a team) and copy its key. For configuration access, an owner or admin creates a key under Settings > App Settings > API Key Management and picks its access rights.

What is a GenieKey? It's the prefix Opsgenie uses in the authorization header. Every request sends Authorization: GenieKey <your-api-key>.

Why does my API Key Management key get an error when creating alerts? Account-level keys from API Key Management can't create, acknowledge, or close alerts, or add notes. Use an API integration key for those calls.

Why does the Opsgenie create alert API return 202 instead of the alert? Alert requests are processed asynchronously. The 202 response includes a requestId, and GET /v2/alerts/requests/:requestId returns the result and the alert ID.

What are the Opsgenie API rate limits? They vary by plan, user count, and API domain, with separate per-minute and per-second limits. Opsgenie shows your actual limits under Reports > API Usage and returns 429 when you exceed them.

Will the Opsgenie API keep working after April 5, 2027? No. Atlassian says Opsgenie will no longer be accessible after its end of support date, so every integration and script that calls the API needs a new destination before then.

Start with the inventory

The API changes are usually the least visible part of an Opsgenie migration, because they're spread across scripts, pipelines, and monitors that nobody has looked at in years. A repo-wide search for GenieKey is a quick first step. If Regen is on your shortlist, you can start Regen with its free 30-day trial, point a test script at its generic webhook, and confirm the mapping before touching production.