> For the complete documentation index, see [llms.txt](https://docs.pagerly.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pagerly.io/getting-started/rest-api.md).

# REST API

Key-authenticated endpoints for integrations that cannot sign in - raise incidents from CI, keep the on-call directory in sync, ask who is on call now.

The REST API is for automation that has no person behind it: a deploy pipeline raising an incident, an HR sync updating phone numbers, a script asking who is on call. For managing teams, rotations and overrides from code, use the [MCP server](/getting-started/connect-an-ai-agent-mcp.md) - it exposes the full write surface.

## 1. Create a key

An **org admin** opens **API Keys** in the dashboard's main menu and clicks *Generate API key*. Copy it once and store it like a password - a key acts as the person who created it.

## 2. Call an endpoint

Send the key in the `X-APIKEY` header.

```bash
# Check the key
curl -H "X-APIKEY: $PAGERLY_KEY" https://api.pagerly.io/o/test/apikey

# Who is on call right now, every team
curl -H "X-APIKEY: $PAGERLY_KEY" https://api.pagerly.io/o/currentusers

# Raise an incident from a pipeline
curl -X POST https://api.pagerly.io/o/incident \
  -H "X-APIKEY: $PAGERLY_KEY" -H "Content-Type: application/json" \
  -d '{ "title": "Checkout error rate above 5%", "severity": "P2" }'
```

## Endpoints

| Method   | Path                                       | Purpose                                         |
| -------- | ------------------------------------------ | ----------------------------------------------- |
| `POST`   | `/o/incident`                              | Create or update an incident                    |
| `GET`    | `/o/currentusers`                          | Who is on call now, every team                  |
| `GET`    | `/o/zapier/allteams`                       | Every team's `id` and `name`                    |
| `GET`    | `/o/oncalluser?email=`                     | One directory entry                             |
| `POST`   | `/o/oncalluser`                            | Create or replace a directory entry (org admin) |
| `POST`   | `/o/oncalluser/phone`                      | Update a phone number                           |
| `POST`   | `/o/oncalluser/role`                       | Change a role (org admin)                       |
| `DELETE` | `/o/oncalluser?email=`                     | Remove from the directory (org admin)           |
| `POST`   | `/o/zapier/subscribe`, `/o/make/subscribe` | Hooks for on-call changes (Zapier, Make)        |

Alerts from monitoring tools do not use this API - each tool gets its own webhook URL from **Integrations** in the dashboard.

{% hint style="info" %}
Full reference with request and response shapes: [pagerly.io/docs/api](https://www.pagerly.io/docs/api). Managing teams and rotations from code, and the Terraform provider, are covered there too.
{% endhint %}