# API authentication (https://docs.pagermate.com/docs/api/authentication)
## Create credentials [#create-credentials]
1. Sign in as an organisation administrator.
2. Open your profile menu, then **Settings → Organization**.
3. In API credentials, create a credential with a useful name, such as `Production monitoring`.
4. Copy the client key and the secret shown in the dialog.
5. Store the secret before closing the dialog.
The secret is displayed once. It is stored as a hash and cannot be recovered later. If it is lost, rotate the credential or create a replacement.
## Credential format [#credential-format]
New credentials use:
- Client key: `pmc_` followed by 32 hexadecimal characters.
- Client secret: `pms_` followed by 32 hexadecimal characters.
Earlier credentials with longer secrets remain accepted until rotated or revoked. Do not shorten an existing secret yourself.
Send both fields using the exact parameter names `client_key` and `client_secret`. A client key is not a service ID, and the endpoint does not use a Bearer token in place of these form fields.
Credentials are scoped to their organisation. A service or incident outside that organisation is not accessible through them.
## Rotate safely [#rotate-safely]
**Rotate credentials** immediately replaces both the client key and secret. Any integration using the old pair stops authenticating.
For a replacement without interrupting an integration:
1. Create a second named credential.
2. Store it and update the integration to use it.
3. Send a controlled test incident and confirm success.
4. Revoke the previous credential after confirming all callers have switched.
There can be at most 20 non-revoked credentials per organisation. Revoke unused credentials before adding more.
## Revoke access [#revoke-access]
Revoke a credential when an integration is retired or the secret is exposed. Revocation blocks new authenticated requests. It does not remove incidents or their timeline history.
## Keep credentials separate from examples [#keep-credentials-separate-from-examples]
Use environment variables or your monitoring platform’s secret storage. Do not put secrets in URLs, browser links, screenshots, tickets, or committed scripts. The API rejects query parameters; credentials belong in the HTTPS form body.
# Deduplication and retries (https://docs.pagermate.com/docs/api/deduplication)
## Two different problems [#two-different-problems]
**Deduplication** groups recurring monitoring reports into one open incident. Each grouped report adds an alert to the timeline.
**Idempotency** recognises a retry of the exact same request. It replays the original response without adding another incident or timeline entry.
## No key: group by service [#no-key-group-by-service]
With service deduplication enabled, a trigger without `deduplication_key` matches the latest triggered or acknowledged incident for that service inside the configured window. The title does not have to match. An unkeyed request can also join an eligible incident that was originally created with a key.
For example, with a 120-second window:
| Time since creation | Incoming title | Outcome |
| --- | --- | --- |
| 0 seconds | Database unavailable | Create an incident |
| 10 seconds | Connection timeout | Add an alert to that incident |
| 50 seconds | Replication lag | Add an alert to that incident |
| 121 seconds | Connection timeout | Create another incident |
The window is measured from incident creation, not from the most recent alert. Repeats do not extend it.
## With a key: match service and key [#with-a-key-match-service-and-key]
Add an explicit key when one service has independent checks:
```bash
--form-string "deduplication_key=production-db-connectivity"
```
A trigger with this key matches only an open incident for the same service with the same key inside the window. A different key creates a separate incident. Changing the title while keeping the same key does not force a new incident.
Choose a stable key such as a check name or monitored resource identifier. Do not generate a new random key for every polling cycle if you want those cycles grouped.
## Service settings still apply [#service-settings-still-apply]
When deduplication is disabled, triggers create new incidents even if an explicit key is supplied. A resolved incident is not a deduplication candidate. The newest matching open incident is used when several are eligible.
Grouping preserves the existing title, description, severity, and acknowledged state. It records that another API alert was received; it does not overwrite the incident with the latest request fields.
## Retry an exact request safely [#retry-an-exact-request-safely]
Add a unique identifier for a single monitoring event:
```bash
--header "Idempotency-Key: monitoring-event-20261031-0001"
```
Reuse it only when retrying that same event with the same fields. A distinct later event needs a distinct idempotency key.
- The API retains the stored response for 24 hours.
- An identical retry returns the original response and HTTP status, including `201` if that was the original result.
- Reusing the key with different fields returns `409`.
- Idempotency is scoped to the API credential, so changing credentials does not preserve that retry identity.
- After expiry, the request is processed again; normal deduplication then determines whether to group it.
Use idempotency when a timeout leaves you unsure whether the server processed the request. Use deduplication for continuing reports of the same service problem.
# API errors and troubleshooting (https://docs.pagermate.com/docs/api/errors)
## Inspect the response [#inspect-the-response]
Use `curl --fail-with-body` to retain the error body while still receiving a nonzero exit status for HTTP errors. Check the HTTP status and JSON message before retrying.
| Status | What to check |
| --- | --- |
| `400` | Use HTTPS and remove all query parameters |
| `401` | Correct client key and secret; credential not revoked or rotated |
| `404` | Public service ID and incident identifier belong to the credential’s organisation |
| `409` | Idempotency key reused with changed fields, or an invalid state transition |
| `413` | Request exceeds the server’s body-size limit |
| `415` | Send multipart form data or URL-encoded fields, not JSON or files |
| `422` | Inspect field errors; active service, valid severity, required identifiers and limits |
| `429` | Respect `Retry-After`; reduce frequency |
| `500` | Retain the response context and contact support; retry a trigger with idempotency |
## Authentication fails after rotation [#authentication-fails-after-rotation]
Rotation replaces both the client key and secret. Update both environment variables. Existing longer secrets remain valid, but truncating them does not produce a valid shorter credential.
## A service cannot be found [#a-service-cannot-be-found]
Copy the 32-character public ID from the service edit page or select the service in the Settings code example. Do not copy the numeric ID from the page URL. Check that the credential belongs to the same organisation.
## Repeated alerts still create incidents [#repeated-alerts-still-create-incidents]
Check the service’s deduplication toggle, its window, whether the previous incident is already resolved, and whether your explicit key changes between requests. Read [Deduplication and retries](/docs/api/deduplication).
## Rate limits [#rate-limits]
Each credential is limited to 120 requests per minute. A separate limit of 600 requests per minute applies per source IP. Several integrations sharing an outbound IP can therefore encounter the IP limit.
Wait for the delay in `Retry-After`. Do not use an immediate retry loop. Reuse the event’s idempotency key when retrying an uncertain trigger request.
## TLS or connection errors [#tls-or-connection-errors]
A TLS handshake failure happens before the incident endpoint receives the form. Test without credentials first:
```bash
curl -q -v --noproxy '*' https://api.pagermate.com/health
```
Check the destination IP, certificate hostname, certificate validation, system clock, DNS resolver, and proxy settings. Do not disable certificate validation with `-k` as a permanent fix. Do not include API credentials in a verbose diagnostic trace sent to support.
## Include useful support details [#include-useful-support-details]
Provide the approximate time and timezone, public service or incident ID, HTTP status, response message, and a redacted command. Omit secrets, passwords, and access tokens. See [Contact support](/docs/support).
# Request fields (https://docs.pagermate.com/docs/api/fields)
## Common fields [#common-fields]
| Field | Required | Description |
| --- | --- | --- |
| `client_key` | Yes | Organisation API client key |
| `client_secret` | Yes | Corresponding secret |
| `service_id` | Yes | Permanent 32-character lowercase hexadecimal service ID |
| `action` | No | `trigger` (default), `acknowledge`, or `resolve` |
| `source` | No | Human-readable monitoring source, up to 100 characters |
| `idempotency_key` | No | Exact-request retry identifier, 1–128 characters |
## Trigger fields [#trigger-fields]
| Field | Required | Description |
| --- | --- | --- |
| `title` | For `trigger` | Incident title, up to 255 characters; surrounding whitespace is trimmed |
| `body` | No | Description, up to 10,000 characters |
| `severity` | No | `low`, `medium`, `high` (default), or `critical` |
| `deduplication_key` | No | Recurring alert identifier, up to 255 characters |
A service must be active to accept a new trigger. Explicit keys do not override a service’s disabled deduplication setting or extend its window.
## Lifecycle fields [#lifecycle-fields]
For `acknowledge` and `resolve`, provide at least one of:
| Field | Description |
| --- | --- |
| `incident_id` | Public incident number, for example `INC-1000000` |
| `deduplication_key` | Find the latest open incident with this key on the selected service |
When both are supplied, `incident_id` identifies the incident. A title is not required for lifecycle updates.
The API has no `unacknowledge`, `reopen`, or delete action. Use the workspace for unacknowledging or reopening.
## Idempotency header [#idempotency-header]
You can send `Idempotency-Key` instead of the `idempotency_key` form field. When both are sent, the header takes precedence. See [Deduplication and retries](/docs/api/deduplication).
## Unsupported fields and formats [#unsupported-fields-and-formats]
Do not send `organizations_id`, `assigned_users_id`, or `status`; these are not accepted public request fields. Choose a supported `action` rather than attempting to set status directly.
Do not send query parameters, JSON bodies, or uploaded files. The server limits request bodies to 64 KiB; individual field limits still apply.
## Response conventions [#response-conventions]
Success responses use `success: true` and a `data` object. The incident includes its public identifier, public service ID, title, severity, status, deduplication result, and timestamps.
Errors use a non-2xx HTTP status. Inspect the returned JSON message and any validation errors rather than assuming every response body represents success.
# Send your first incident (https://docs.pagermate.com/docs/api)
## Before you start [#before-you-start]
You need an active [service](/docs/guides/services), its public service ID, and API credentials created by an organisation administrator. Read [Authentication](/docs/api/authentication) if you have not created credentials yet.
The public endpoint is:
```text
POST https://api.pagermate.com/v1/incident
```
This is a server-to-server API. Send credentials in the request body over HTTPS. The API accepts multipart form data and URL-encoded forms, not JSON, file uploads, or query parameters.
## Prepare your environment [#prepare-your-environment]
Set your own credential values and service ID in your shell or your monitoring system’s secret store:
```bash
export PAGERMATE_CLIENT_KEY='pmc_REPLACE_WITH_YOUR_CLIENT_KEY'
export PAGERMATE_CLIENT_SECRET='pms_REPLACE_WITH_YOUR_CLIENT_SECRET'
export PAGERMATE_SERVICE_ID='REPLACE_WITH_YOUR_32_CHARACTER_SERVICE_ID'
```
These are placeholders, not working credentials. Keep the secret out of source control and shared command output.
## Create an incident [#create-an-incident]
```bash
curl --fail-with-body --silent --show-error \
https://api.pagermate.com/v1/incident \
--form-string "client_key=$PAGERMATE_CLIENT_KEY" \
--form-string "client_secret=$PAGERMATE_CLIENT_SECRET" \
--form-string "service_id=$PAGERMATE_SERVICE_ID" \
--form-string "title=Database unavailable" \
--form-string "body=Connection checks are failing" \
--form-string "severity=critical" \
--form-string "source=Database health check"
```
`--form-string` sends literal values, including text that might otherwise be interpreted as a file upload by curl.
A successful creation returns HTTP `201` and JSON like this illustrative response:
```json
{
"success": true,
"data": {
"incident_id": "INC-1000000",
"service_id": "00000000000000000000000000000000",
"title": "Database unavailable",
"severity": "critical",
"status": "triggered",
"deduplicated": false,
"created_at": "2026-10-31T10:00:00+00:00",
"acknowledged_at": null,
"resolved_at": null
}
}
```
Save the actual `incident_id` returned by your request for later updates. API timestamps are ISO 8601 timestamps with a timezone offset; the workspace displays them in the organisation timezone.
## Send URL-encoded data instead [#send-url-encoded-data-instead]
```bash
curl --fail-with-body --silent --show-error \
https://api.pagermate.com/v1/incident \
--data-urlencode "client_key=$PAGERMATE_CLIENT_KEY" \
--data-urlencode "client_secret=$PAGERMATE_CLIENT_SECRET" \
--data-urlencode "service_id=$PAGERMATE_SERVICE_ID" \
--data-urlencode "title=Database unavailable" \
--data-urlencode "severity=critical"
```
## Next steps [#next-steps]
- [Request field reference](/docs/api/fields).
- [Acknowledge and resolve](/docs/api/lifecycle).
- [Group alerts and retry safely](/docs/api/deduplication).
- [Diagnose errors](/docs/api/errors).
# Acknowledge and resolve incidents (https://docs.pagermate.com/docs/api/lifecycle)
Use the credentials and service ID from the [first request](/docs/api). Replace `INC-1000000` with the actual identifier returned by your trigger request.
## Acknowledge by incident number [#acknowledge-by-incident-number]
```bash
curl --fail-with-body --silent --show-error \
https://api.pagermate.com/v1/incident \
--form-string "client_key=$PAGERMATE_CLIENT_KEY" \
--form-string "client_secret=$PAGERMATE_CLIENT_SECRET" \
--form-string "service_id=$PAGERMATE_SERVICE_ID" \
--form-string "action=acknowledge" \
--form-string "incident_id=INC-1000000"
```
This returns HTTP `200` with `status: acknowledged`. API actions are recorded as API activity rather than as a signed-in human agent taking ownership. To take personal ownership, acknowledge from the workspace.
## Resolve by incident number [#resolve-by-incident-number]
```bash
curl --fail-with-body --silent --show-error \
https://api.pagermate.com/v1/incident \
--form-string "client_key=$PAGERMATE_CLIENT_KEY" \
--form-string "client_secret=$PAGERMATE_CLIENT_SECRET" \
--form-string "service_id=$PAGERMATE_SERVICE_ID" \
--form-string "action=resolve" \
--form-string "incident_id=INC-1000000"
```
The response includes `status: resolved` and `resolved_at`. Resolving the same incident again by its incident number succeeds without adding another status-change event.
## Recover by explicit key [#recover-by-explicit-key]
If your trigger included `deduplication_key=production-db-connectivity`, a recovery check can resolve the latest open incident with that key:
```bash
curl --fail-with-body --silent --show-error \
https://api.pagermate.com/v1/incident \
--form-string "client_key=$PAGERMATE_CLIENT_KEY" \
--form-string "client_secret=$PAGERMATE_CLIENT_SECRET" \
--form-string "service_id=$PAGERMATE_SERVICE_ID" \
--form-string "action=resolve" \
--form-string "deduplication_key=production-db-connectivity"
```
Key-based lifecycle lookup is scoped to the selected service and finds an open incident. Once no matching open incident remains, repeating that key-based resolution returns `404`. Use `incident_id` or an idempotency key when you need a repeatable exact recovery update.
## State rules [#state-rules]
- Trigger reports group only with triggered or acknowledged incidents when deduplication applies.
- A resolved incident cannot be acknowledged through the API; that returns `409`.
- Triggering after resolution creates a new incident rather than reopening the resolved record.
- You can acknowledge or resolve existing incidents even if their service has since been marked inactive. New triggers for that inactive service are rejected.
- The public API does not delete incidents or reopen them.
# Set up your first workspace (https://docs.pagermate.com/docs/getting-started)
This walkthrough uses a production database service as an example. Use your own service and agent names.
## 1. Choose your organisation timezone [#1-choose-your-organisation-timezone]
1. Open your profile menu and choose **Settings**.
2. Open **Organization** as an organisation administrator.
3. Select the timezone your team uses, for example `Europe/Vienna`.
4. Save the change.
Displayed dates, vacation days, schedule inputs, and report day boundaries use the organisation timezone. Set it before planning coverage. See [Settings](/docs/guides/settings).
## 2. Add responders [#2-add-responders]
Open **Agents**, create the people who will respond, and enter their names and email addresses. Creation opens the agent’s edit page. You do not choose an initial password in this form.
Record planned vacation on the agent’s detail page before building a rotation. See [Agents](/docs/guides/agents) and [Vacations and overrides](/docs/guides/overrides-vacations).
## 3. Create an on-call schedule [#3-create-an-on-call-schedule]
Open **Schedules → Overview**, choose **Create schedule**, and enter:
- A recognisable name, such as `Platform primary`.
- A rotation start date and local handoff time.
- A handoff frequency, for example weekly.
- The agents, in the order they should rotate.
Review the coverage preview and save. A schedule that starts in the future is not yet covering the current time. See [Schedules](/docs/guides/schedules).
## 4. Define an escalation policy [#4-define-an-escalation-policy]
Create a policy with your schedule in the first level and a backup agent or schedule in a later level. Set the response window and any repeats, then save. See [Escalation policies](/docs/guides/escalation-policies).
These settings describe the intended routing. They do not start sending notifications while the notification engine is pending.
## 5. Create the monitored service [#5-create-the-monitored-service]
Open **Services**, create `Production database`, and select the policy. Enable deduplication and choose a window appropriate for your monitoring frequency, for example 120 seconds.
Save and copy the permanent public service ID from the edit page. See [Services](/docs/guides/services).
## 6. Connect a monitoring check [#6-connect-a-monitoring-check]
An organisation administrator creates credentials in **Settings → Organization**, in the API credentials section. Store the secret when it is shown.
Follow the [first API request](/docs/api) using those credentials and the service’s public ID. Do not send a numeric service ID.
## 7. Verify the complete result [#7-verify-the-complete-result]
1. Confirm that the API returned an `INC-...` identifier.
2. Open **Incidents** and find the new incident.
3. Repeat the request within the deduplication window and check that it adds an alert to the same incident.
4. Acknowledge the incident, add an investigation comment, and resolve it.
5. Check the timeline and [Reports](/docs/guides/dashboard-reports).
This verifies ingestion and the incident workflow. It does not verify outgoing notifications, which are not active yet.
# Manage agents (https://docs.pagermate.com/docs/guides/agents)
## Create and edit an agent [#create-and-edit-an-agent]
1. Open **Agents** and choose the create action.
2. Enter the responder’s name and email address.
3. Create the agent. The agent’s edit page opens.
4. Update **User data** and choose **Save changes** when needed.
The create form does not ask for an initial password or an active/inactive choice. Creating an agent does not send an invitation email automatically.
Use the overview’s search to find a responder. Click the row to open their detail page; the three-dot menu contains enable/disable and delete actions.
## Understand agent statistics [#understand-agent-statistics]
The detail page shows resolved incidents, acknowledged incidents, open assignments, recent resolutions, and timing averages.
- **Average acknowledgement:** elapsed time from incident creation to acknowledgement, for the agent’s recorded acknowledgements.
- **Average resolution:** elapsed time from creation to resolution, for recorded resolutions.
- **Sample count:** how many valid incidents contribute to an average.
- **Recent incidents:** up to ten recently updated incidents associated with the agent’s assignment, acknowledgement, or resolution.
Missing or invalid timestamps do not count as zero-second responses. An absent average means there are no valid samples. Averages are not a measure of time spent actively working.
## Record vacation [#record-vacation]
Use the **Vacations** section on the detail page. Vacation is recorded as whole days in the organisation timezone. Read [Vacations and overrides](/docs/guides/overrides-vacations) before making coverage changes.
## Disable or delete safely [#disable-or-delete-safely]
If PagerMate blocks disabling or deleting an agent, resolve the references first:
1. Remove them from schedule membership.
2. Replace or cancel their active or upcoming overrides.
3. Remove them from escalation policy levels.
4. Reassign their open incidents where applicable.
5. Retry the action.
Prefer disabling an account when you want to keep it for reference. Deletion is a separate action and should not be used as a substitute for planning replacement coverage.
## Organisation access and system administration [#organisation-access-and-system-administration]
An organisation administrator is different from a system administrator. The system-wide **Admin** menu is restricted to system administrators; creating an ordinary agent does not grant system-wide access.
# Use the dashboard and reports (https://docs.pagermate.com/docs/guides/dashboard-reports)
## Dashboard [#dashboard]
The dashboard uses a fixed 30-day period for its period-based metrics. Current open counts and coverage describe the current state.
The incident list shows up to ten incidents in this order:
1. Triggered.
2. Acknowledged.
3. Resolved.
Within each status, newer incidents appear first. Status priority is applied before the ten-row limit, so an older triggered incident can appear ahead of a recent resolved incident. Open **Incidents** for the full overview.
The open-incidents card is red when any incident is triggered, blue when there are acknowledged incidents but none triggered, and green when neither is open.
**On-call now** lists schedules first and their current responders underneath. Review future start times, pauses, and vacation if coverage is missing.
## Change the report period [#change-the-report-period]
1. Open **Reports** under **Organisation**.
2. Choose **Last 7 days**, **Last 30 days**, or **Last 90 days**, or enter a custom start and end date.
3. For a custom range, choose **Apply range**.
4. Wait for the results before interpreting or exporting them.
Dates are inclusive and use the organisation timezone. The maximum range is 366 days, and the end cannot be after today. Editing dates without applying the range does not change the displayed results.
## Read the graphs correctly [#read-the-graphs-correctly]
- **Incidents created:** incidents whose creation falls in the selected range.
- **Currently resolved:** incidents created in the range that are currently resolved.
- **Mean acknowledgement and resolution:** elapsed time from creation, using valid recorded timestamps.
- **Daily created and resolved:** events on each date. Resolutions can include incidents created before the range.
- **Severity and service breakdowns:** incidents created in the selected range, grouped by those fields.
Daily resolution totals therefore need not equal the number of currently resolved incidents created during the range. Averages exclude missing, future, or invalid timing samples; a graph gap does not mean zero seconds.
## Export daily data [#export-daily-data]
Choose **Export daily CSV** to download the daily rows for the currently displayed range. Apply any pending date changes before exporting. Use the service breakdown to identify which monitored systems contributed most incidents.
## Compare an agent’s results [#compare-an-agents-results]
The [agent detail page](/docs/guides/agents) has agent-specific statistics. Its sample and time scope can differ from the organisation report, so compare the labels and sample counts before comparing averages.
# Configure escalation policies (https://docs.pagermate.com/docs/guides/escalation-policies)
## Create a policy [#create-a-policy]
1. Open **Escalation** in the sidebar.
2. Create a policy with a recognisable name and description.
3. Add the first level’s targets.
4. Set the response window before moving to the next level.
5. Add backup levels and choose whether the policy should repeat.
6. Connect the intended services and save.
A target can be an individual agent or an on-call schedule. Multiple targets can be configured in one level. Use the three-dot menu on the overview for policy actions.
## When to use an agent or a schedule [#when-to-use-an-agent-or-a-schedule]
An **agent** target always names a specific person. A **schedule** target names the rotation, so the currently on-call person can change without editing the policy.
Use a schedule for primary coverage that rotates. Use an individual agent for a person who should explicitly be part of a level. You can combine them when both are intentional, for example a rotating responder and a fixed incident coordinator.
## Understand levels and repeats [#understand-levels-and-repeats]
The first level represents the first configured recipients. Later levels represent the fallback path if the incident is not acknowledged within the preceding level’s response window.
**Do not repeat** means one pass. A repeat count means additional passes after that first pass. For example, repeating twice means three passes in total.
These values currently configure the intended process. **The notification and escalation execution engine is not active yet**, so saving a policy does not begin sending alerts or advancing timers.
## Connect services [#connect-services]
A service can use one policy. You can choose the policy on the service edit page or manage connected services in the policy editor. Moving a service to a different policy replaces its previous policy connection.
## Example configuration [#example-configuration]
| Level | Target | Purpose |
| --- | --- | --- |
| 1 | Platform primary schedule | Current primary responder |
| 2 | Platform backup schedule | Secondary coverage |
| 3 | Incident coordinator agent | Explicit final contact |
Choose response windows based on your team’s operating procedure. Ensure each schedule has coverage before relying on that route.
## Resolve missing targets [#resolve-missing-targets]
An agent or schedule must be enabled to be newly selected. If an item is unavailable, check its state, membership, start time, and coverage. Record vacation and overrides in their own pages; they are not policy levels.
# Work an incident (https://docs.pagermate.com/docs/guides/incidents)
## Find or create an incident [#find-or-create-an-incident]
Open **Incidents** to search and review the overview. Click a row to open its detail page. Public identifiers use the format `INC-1000000`.
To create an incident manually, use **New incident**, enter a title and description, choose a service and severity, and submit. The form does not include an assignee field. Monitoring systems can use the [Incident API](/docs/api).
## Understand the statuses [#understand-the-statuses]
| Status | Meaning | Available actions |
| --- | --- | --- |
| Triggered | The incident needs attention | Acknowledge, resolve |
| Acknowledged | Someone has taken ownership | Unacknowledge, resolve |
| Resolved | The issue is marked complete | Reopen incident |
Acknowledging from the workspace assigns the incident to the current user and records who acknowledged it and when. Unacknowledging returns it to triggered. Resolving records the resolution and a timeline entry.
Reopening returns a resolved incident to triggered and clears its current acknowledgement and resolution timestamps. Historical timeline entries remain. Reopen first if you need to acknowledge a resolved incident in the workspace.
## Record the investigation [#record-the-investigation]
Add comments with useful observations, mitigation steps, and next actions. The activity timeline includes incident creation, monitoring updates, status changes, and comments.
Use the timeline filters, search, and sort control to find a particular update. Copy the incident link when you need to refer colleagues to the same record.
Example comment:
> Confirmed connection failures from both application hosts. Restarted the connection pool at 14:10. Monitoring recovery before resolving.
## Read elapsed time [#read-elapsed-time]
The timer beside the title measures creation to the current time for an open incident, or creation to resolution for a resolved incident. It is hidden on smaller screens. Action buttons sit below the title.
On the overview, recent creation times are relative and update while the page is open. Very recent incidents show **now**, then minutes and hours; older dates show date and time in the organisation timezone.
## Handle repeated reports [#handle-repeated-reports]
A grouped API alert adds a monitoring entry instead of creating a new incident. It does not replace the existing incident’s title, description, severity, or acknowledged state. Read [Deduplication and retries](/docs/api/deduplication) to understand the grouping window.
## Recommended response workflow [#recommended-response-workflow]
1. Read the service and the initial report.
2. Acknowledge when you take ownership.
3. Record findings and mitigation in comments.
4. Verify recovery using your monitoring system.
5. Resolve with a final comment describing the outcome.
No outgoing notifications are sent by these actions while notification delivery is inactive.
# Vacations and coverage overrides (https://docs.pagermate.com/docs/guides/overrides-vacations)
## Choose the right feature [#choose-the-right-feature]
| Situation | Use |
| --- | --- |
| An agent is unavailable for whole days | Vacation on the agent detail page |
| Someone covers a specific time interval | Schedule override |
| The recurring responder order changes | Edit the schedule |
Vacation declares unavailability; it does not choose a replacement. An override replaces the schedule’s normal responder for a defined interval and returns to the base rotation afterward.
## Add vacation [#add-vacation]
1. Open **Agents** and select the agent.
2. In **Vacations**, choose **Add vacation**.
3. Select the first and last day and optionally enter a reason.
4. Save and review affected schedules.
Both dates are included. A one-day vacation means choosing the same start and end date. Days use the organisation timezone.
Vacation can start today or later, cover at most 366 days, and must stay within five years. Overlapping vacation entries are rejected. An organisation administrator can manage agents’ vacation; an agent can manage their own.
If the agent already covers an active or upcoming override during the dates, replace or cancel that override before adding vacation. Existing base rotation membership can become a coverage gap, so check the schedule timeline afterward.
## Create a coverage override [#create-a-coverage-override]
1. Open **Schedules → Overrides**, or the schedule’s **Coverage overrides** section.
2. Choose the create override action and select a schedule.
3. Enter the start and end time.
4. Choose an available replacement responder.
5. Add a reason, such as `Covering annual leave`, and save.
The schedule must be enabled. The replacement must be enabled and available for the full interval. An override cannot start before its schedule starts, overlap another override on that schedule, or last more than 93 days. The end must be in the future and within five years.
## Edit or cancel [#edit-or-cancel]
- Upcoming overrides can be edited.
- To change an active override, cancel it and create the replacement.
- Canceling an active override ends it now and restores the base rotation from that point.
- Canceling an upcoming override removes the planned replacement.
- Past overrides remain as coverage history.
Past or canceled vacation remains in history. Canceling active vacation ends its unavailability now rather than rewriting the past.
## Example: cover annual leave [#example-cover-annual-leave]
Sam is on vacation Monday through Friday. Alex agrees to cover the affected shifts.
1. Check whether Sam already has any overrides in that week and replace or cancel them.
2. Add Sam’s whole-day vacation.
3. Review the schedule for gaps.
4. Add an override assigning Alex for each required coverage interval.
5. Verify the timeline and **On call now** when the interval begins.
# Build on-call schedules (https://docs.pagermate.com/docs/guides/schedules)
## Create a rotation [#create-a-rotation]
1. Expand **Schedules** in the sidebar and open **Overview**.
2. Choose **Create schedule**.
3. Enter a unique, descriptive name and an optional description.
4. Set **Rotation starts** and **Handoff frequency**.
5. Add responders and arrange their order.
6. Review the preview and save.
You can use daily, weekly, two-week handoffs, or a custom interval of 1–30 days. The first responder starts at the selected time. The rotation then repeats in membership order.
For example: Monday 09:00, weekly, with Alex followed by Sam, gives Alex the first week and Sam the next.
## Preview before saving [#preview-before-saving]
The editor previews the first 14 days. Check the start time, responder order, handoffs, and vacation conflicts. Previewing does not save changes.
Inputs use the organisation timezone. Handoffs follow the schedule’s local calendar timing, so daylight-saving transitions can affect the elapsed number of hours in a day. When a local handoff is skipped by a clock change, it moves forward with the clock.
## Read the overview [#read-the-overview]
Use **All**, **Covered**, **Gaps**, and **Paused** to filter schedules. Search by schedule or person. Pagination defaults to ten rows.
- **On call now:** the current responder, including an active override.
- **Not started yet:** the start time is still in the future.
- **No coverage:** an enabled schedule has no available responder at the current time.
- **Paused:** the schedule is disabled.
Coverage refreshes every minute on the overview. Open the schedule for its timeline, upcoming shifts, overrides, and linked policies.
## Handle vacation [#handle-vacation]
An agent on vacation is unavailable during the conflicting period. The editor disables conflicting choices and validates coverage when you save. PagerMate does not silently substitute the next person in the rotation; a vacation can create a gap.
Choose another responder, change the rotation, or arrange appropriate override coverage. See [Vacations and overrides](/docs/guides/overrides-vacations).
## Connect a schedule to a service [#connect-a-schedule-to-a-service]
Schedules are targets inside [escalation policies](/docs/guides/escalation-policies). Add the schedule to a policy level, then select that policy on the [service](/docs/guides/services).
## Pause or delete [#pause-or-delete]
Remove a schedule from any escalation policy targets before pausing or deleting it. PagerMate blocks the action while those references remain. Review future coverage before making the change.
# Configure services (https://docs.pagermate.com/docs/guides/services)
## Create a service [#create-a-service]
1. Open **Services** and choose the create action.
2. Enter a clear name and a description of what is monitored.
3. Choose an escalation policy, if available.
4. Configure incident deduplication.
5. Save.
Click a service row to open its edit view. You can edit and save directly; there is no separate read-only view to pass through.
## Connect the right responders [#connect-the-right-responders]
Select an escalation policy in **Escalation routing**. The policy contains the direct agents and schedules used for that service. To connect a schedule, add it to a policy level and assign that policy to the service.
A service uses one policy at a time. If no policy is selected, there are no configured escalation targets. Policy configuration does not currently activate outgoing notifications.
## Copy the public service ID [#copy-the-public-service-id]
The API uses the service’s permanent 32-character hexadecimal ID. Copy it from the service edit page and pass it as `service_id`.
This ID is generated when the service is created and cannot be edited. A numeric ID appearing in a page URL is not the public API identifier. A service ID from another organisation cannot be used with your API credentials.
## Configure deduplication [#configure-deduplication]
With deduplication enabled, incoming API triggers can join an existing triggered or acknowledged incident within the configured window:
- No explicit key: match the service, regardless of title.
- Explicit key: match that service and key.
The window is measured from the incident’s creation time. Repeated alerts do not restart the window. Resolved incidents do not receive new triggers through deduplication.
For example, with a 120-second window, ten keyless reports received in 50 seconds for the same service become one incident with ten timeline entries. A report after the window may create another incident even if an older one remains open.
See [Deduplication and retries](/docs/api/deduplication) for examples and idempotency.
## Active status versus health [#active-status-versus-health]
**Active/inactive** controls whether the public API accepts new trigger reports for the service. **Health** reflects open incidents: triggered incidents indicate critical health; acknowledged incidents indicate degraded health; no open incidents indicate operational health.
Marking a service inactive does not resolve its existing incidents. Acknowledge or resolve those incidents separately.
## Delete a service [#delete-a-service]
A service with incident history cannot be deleted. Mark it inactive to preserve that history. If you need to remove a service with no history, use its delete action and confirm the selected service.
# Account and organisation settings (https://docs.pagermate.com/docs/guides/settings)
## Open settings [#open-settings]
Open your profile menu and choose **Settings**. Settings are grouped into profile, security, notifications, and organisation sections. Organisation management is restricted to organisation administrators.
## Profile [#profile]
Update your name and email, then save. Changing your email requires your current password. If your account does not yet have password sign-in configured, set that up under **Security** before changing the email address.
## Organisation timezone [#organisation-timezone]
An administrator can change the organisation name and timezone under **Organization**. The workspace displays time in this timezone, including incident dates, schedule inputs, vacation days, and report date boundaries.
Choose a regional timezone such as `Europe/Vienna` to account for daylight-saving changes. Changing the displayed organisation timezone does not mean existing schedules should be assumed to have been rebuilt with a different handoff rule; inspect the schedule preview after a timezone change.
## Password and sessions [#password-and-sessions]
Use **Security** to set or change your password. Changing it revokes sign-in sessions and signs you out, so be ready to sign in again.
The session list shows tracked sessions, their creation and activity times, and which is current. You can revoke an individual session or sign out other sessions. Revoking the current session signs you out of it. If older sessions are not tracked, sign in again to establish a tracked session.
## Notification preferences [#notification-preferences]
Save a notification email, a phone number, preferred contact methods, and the incident events you want to hear about. Leave the notification email blank to use the account email.
SMS and phone-call preferences require an international phone number with a leading `+`, country code, and no spaces, for example `+436601234567`.
**Delivery is not active yet.** These preferences are stored, but no incident emails, texts, push notifications, or calls are sent. Contact methods are not yet verified. Provider plugins are not currently available as a functioning delivery path.
## API credentials [#api-credentials]
Organisation administrators manage API credentials in **Organization**. Create a named credential, store its one-time secret, and choose a service in the Bash example.
Rotating replaces both the key and secret immediately. Revoking prevents further use of that credential. See [API authentication](/docs/api/authentication) for a safe rotation workflow.
## Conflicting changes [#conflicting-changes]
If a save reports that the record changed in another session, reload its current values and review your changes before retrying. Do not repeatedly submit stale values. API credential rotation and revocation also use stale-change protection.
# PagerMate documentation (https://docs.pagermate.com/docs)
## What would you like to do? [#what-would-you-like-to-do]
## How the pieces fit together [#how-the-pieces-fit-together]
| Item | What it represents | Example |
| --- | --- | --- |
| Agent | A person who responds | An infrastructure engineer |
| Schedule | An ordered on-call rotation | Weekly platform coverage |
| Override | Temporary replacement for a schedule | Cover Tuesday afternoon |
| Vacation | Whole days an agent is unavailable | Annual leave |
| Escalation policy | Ordered levels containing agents or schedules | Primary coverage, then backup |
| Service | The application or infrastructure being monitored | Production database |
| Incident | An issue and its investigation history | Database connection failures |
A service connects to an escalation policy. A policy level can point to an individual agent or to a schedule. The schedule determines who is on call for that time.
## Current notification status [#current-notification-status]
Incident creation, history, status changes, schedules, overrides, and reporting work. **Automatic incident notification delivery and escalation execution are not active yet.** Configuring a policy or saving notification preferences does not currently send email, SMS, push notifications, or calls. See [Notification settings](/docs/guides/settings#notification-preferences).
## Find an answer [#find-an-answer]
Use the search button to search these guides. For common problems, start with [Troubleshooting](/docs/troubleshooting). For help from the team, see [Contact support](/docs/support).
## Machine-readable documentation [#machine-readable-documentation]
- [Sitemap](https://docs.pagermate.com/sitemap.xml): homepage and documentation URLs, with source modification dates, change frequencies, and page priorities.
- [llms.txt](https://docs.pagermate.com/llms.txt): the index generated by Fumadocs.
- [llms-full.txt](https://docs.pagermate.com/llms-full.txt): the complete documentation in one text file.
These files regenerate from the current documentation when it is published.
# Contact support (https://docs.pagermate.com/docs/support)
## Use Get help [#use-get-help]
1. Open **Get help** in your PagerMate workspace.
2. Choose a category and enter a reply email.
3. Add a concise subject and describe the problem.
4. Include the related page if useful.
5. Submit and save the support reference.
The request is saved in PagerMate. Its email delivery status describes delivery, not whether support has resolved the issue.
**Automatic support email delivery is not configured yet.** After saving, use the email action to send the request with your mail app, or email [ska@pagermate.com](mailto:ska@pagermate.com) and include the saved reference.
## What to include [#what-to-include]
- What you expected and what happened instead.
- Reproduction steps and the affected page.
- Approximate time and timezone.
- Public incident number or service ID, if relevant.
- For API problems: HTTP status and the returned error message.
- A screenshot or redacted example when it makes the problem clearer.
Do not include client secrets, passwords, access tokens, or private customer data in public examples.
## Check the relevant guide first [#check-the-relevant-guide-first]
# Workspace troubleshooting (https://docs.pagermate.com/docs/troubleshooting)
## Why are there no notifications? [#why-are-there-no-notifications]
Outgoing incident notification delivery and escalation execution are not active yet. Saving contact preferences, schedules, and policies prepares configuration but does not send messages. No amount of re-saving the incident will enable delivery.
## How do I connect a service directly to a schedule? [#how-do-i-connect-a-service-directly-to-a-schedule]
Connect the schedule to an escalation policy level, then assign that policy to the service. See [Escalation policies](/docs/guides/escalation-policies).
## Why is an agent unavailable in the schedule editor? [#why-is-an-agent-unavailable-in-the-schedule-editor]
Check whether the agent is enabled and whether recorded vacation overlaps a planned shift. Review the selected rotation start, order, and interval. Choose a different responder, adjust the rotation, or arrange coverage through [overrides](/docs/guides/overrides-vacations).
## Why does the schedule show a gap? [#why-does-the-schedule-show-a-gap]
Check whether it has started, whether it is paused, whether its responder is enabled and available, and whether an override has ended. Vacation does not automatically move the shift to the next rotation member.
## Why can’t I edit an override? [#why-cant-i-edit-an-override]
Only upcoming overrides can be edited. Cancel an active override and create a replacement. Past overrides are retained as history. Overlapping replacements on the same schedule are rejected.
## Why can’t I disable or delete an item? [#why-cant-i-disable-or-delete-an-item]
Dependency checks preserve current routing and history:
- Agents may still be schedule members, override replacements, policy targets, or assigned to open incidents.
- Schedules may still be targeted by a policy.
- Services with incident history cannot be deleted; mark them inactive instead.
Resolve the dependency named in the error rather than repeatedly retrying deletion.
## Why did saving fail with a changed-record message? [#why-did-saving-fail-with-a-changed-record-message]
Another tab, person, or coverage update may have changed the record. Reload the latest data and review your intended changes before saving again. This also applies to API credential rotation, vacation, and overrides.
## Why do report totals seem different? [#why-do-report-totals-seem-different]
Check whether you are looking at incidents created in the selected range or resolutions that occurred during it. Daily resolutions may include older incidents. Timing averages count only valid samples. See [Dashboard and reports](/docs/guides/dashboard-reports).
## Why is a time different from my device clock? [#why-is-a-time-different-from-my-device-clock]
The workspace uses the organisation timezone. Check **Settings → Organization** and the timezone shown beside coverage or reports. Public API timestamps include a timezone offset instead of using the viewer’s display timezone.
## Why is a support request saved but not emailed? [#why-is-a-support-request-saved-but-not-emailed]
The form stores the request and gives you a reference. Automatic email delivery is not configured yet. Use the offered email action or write to [ska@pagermate.com](mailto:ska@pagermate.com), including that reference.