> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AlertOps

> Connect AlertOps to Serval with a User API key so workflows can manage alerts, incidents, on-call schedules, escalation policies, and inbound/outbound integrations.

## About AlertOps

AlertOps is an incident alerting and on-call management platform. The Serval AlertOps integration connects with a single credential — your AlertOps **User API key** — and gives workflows typed access to every published AlertOps API surface: the modern v2 REST API, the legacy v1 API, and the inbound alert-ingestion endpoint. Serval attaches your key in the right place for each API family automatically (header, query parameter, or request body), so there is nothing technical to configure beyond pasting the key.

**Authentication:** API key (an AlertOps User API key, from your AlertOps user profile)

**Data sync:** On-demand only. Connecting AlertOps does not import alerts or any other records into Serval, and there are no background syncs — all access happens when a workflow runs an AlertOps action.

## What the AlertOps integration enables

| Capability                                        | Description                                                                                                                                                                                                                                                           |
| ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Alert management (v2)                             | Create alerts (with escalation policies, topics, priorities, tags, custom fields, recipients, attachments), assign, close, bulk-assign, bulk-close, add notes and messages, read timelines, notifications, and postmortems, and trigger outbound actions on an alert. |
| Status-page incidents and services (v2)           | Create and update service incidents (investigating → resolved), manage services, components, templates, and subscriber notifications (email, SMS, Slack DM).                                                                                                          |
| Users and contact methods (v2)                    | Create, list, update, and delete users, contact methods, notification times, out-of-office records, and custom user attributes, and read a user's roles.                                                                                                              |
| Groups and topics (v2)                            | Manage groups, group members, group contact methods, and topics.                                                                                                                                                                                                      |
| Escalation policies (v2)                          | Manage escalation policies, member roles, contact-method notification steps, workflows, outbound actions/integrations attached to a policy, and trigger a policy notification directly.                                                                               |
| On-call schedules (v2)                            | Read and manage group schedules, fixed and rotating schedules, and query who is on call right now (`/api/v2/schedules/oncallnow`).                                                                                                                                    |
| Inbound integration configuration (v2)            | Create and manage inbound (API/email) integrations programmatically — mappings, filters, alert grouping/delaying rules, escalation-policy overrides, dynamic recipient groups, and enable/disable status.                                                             |
| Outbound integration configuration (v2)           | Create and manage outbound integrations and their methods (templated REST calls AlertOps makes to other systems).                                                                                                                                                     |
| Maintenance windows, bridges, workflows (v2 + v1) | Manage maintenance windows, conference bridges, and AlertOps workflows (conditions and actions).                                                                                                                                                                      |
| Legacy v1 API                                     | The full legacy surface — RPC-style endpoints like `/api/alert/Create`, `/api/user/ListUsers`, `/api/schedule/Oncallnow`, and inbound-message lookups (`GetAlertIDByInboundMessageID`) — for accounts and scripts still built against v1.                             |
| Inbound alert ingestion                           | Post events to an AlertOps inbound (API) integration exactly as a monitoring tool would, driving the integration's field mapping and open/update/close rules, via the built-in **AlertOps send inbound alert** action.                                                |

The v2 and legacy v1 APIs are exposed as two separate typed actions (**AlertOps API request** and **AlertOps legacy v1 API request**). Prefer v2 — it is RESTful, accepts names where v1 requires numeric IDs, and covers nearly everything — and reach for v1 only where your account's tooling depends on it.

## Get your credentials

<Steps>
  <Step title="Open your AlertOps profile">
    Sign in to AlertOps and click your username in the top-right corner, then select **Profile**.
  </Step>

  <Step title="Copy your API key">
    Find the **API Key** section (shown partially masked) and use **Copy** to copy the full key.
  </Step>
</Steps>

<Warning>
  The key is tied to your AlertOps user. Results of user-scoped reads (for example listing alerts with the default "view by user" filter) are relative to that user, and the key carries that user's permissions. For team automation, use a dedicated service user rather than a personal account.
</Warning>

<Warning>
  **Regenerate** in the profile immediately invalidates the old key. If someone regenerates it, workflows start failing with 401s until you paste the new key into the Serval connection.
</Warning>

## Connect in Serval

<Steps>
  <Step title="Open the AlertOps integration">
    In Serval, open the **AlertOps** integration's connect form.
  </Step>

  <Step title="Paste your API key">
    Paste the User API key into the **API Key** field (a masked password field).
  </Step>

  <Step title="Submit">
    Submit the form to finish connecting.
  </Step>
</Steps>

When you reopen the connection settings, the stored key is shown obfuscated. Saving the form without changing the field keeps your existing key — you only paste a new value when rotating it.

## Verifying the connection

The integration ships four health checks, visible on the integration's settings page:

1. **Test AlertOps Connection** — authenticates against the v2 API.
2. **List AlertOps Groups** — confirms group read access.
3. **List AlertOps Escalation Policies** — confirms escalation-policy read access (needed to create alerts).
4. **List Integrations (Legacy v1 API)** — exercises the legacy v1 API's separate query-parameter auth path.

If the first three pass but the legacy check fails, v2 workflows still work fine — see the gotchas below.

## Sending alerts into AlertOps

Workflows have two ways to raise an AlertOps alert:

* **Direct (recommended):** use the **AlertOps API request** action with `POST /api/v2/alerts`, specifying an escalation policy or response play by name. This is fully typed and requires no AlertOps-side setup.
* **Through an inbound integration:** use the **AlertOps send inbound alert** action to POST a payload to `https://notify.alertops.com/POSTAlert/{endpointToken}/{source}`, exactly as a monitoring tool would. This drives the inbound integration's field mapping and its "Open / Update / Close Alert When" rules — useful when you want AlertOps-side grouping, delaying, filters, or escalation-policy overrides applied. Create the inbound integration in AlertOps under **Configurations → Integrations → Inbound Integrations → + ADD API**, then copy the endpoint token (the UUID in the generated URL) and the trailing source segment into the action's inputs.

Keep the inbound integration's **Method** as `POST` and **Content** as `JSON` (both defaults) — the action sends a JSON POST, and AlertOps also offers GET and form-encoded modes that it cannot drive. Nested payload values are fine: map them on the AlertOps side with the caret syntax (`issue^id`), and array elements as `evalMatches_0^metric`.

<Note>
  The inbound endpoint URL embeds its own credential (the endpoint token) — treat the token like a secret. Serval deliberately sends no API key to `notify.alertops.com`. For the same reason, leave the integration's **Authorization Header** option off: Serval's proxy strips `Authorization` headers from workflow requests, so an inbound integration requiring one cannot be driven from a workflow.
</Note>

## Triggering Serval workflows from AlertOps

AlertOps can call Serval when alerts change state (opened, assigned, closed, escalated, SLA thresholds, and any other condition expressible in an AlertOps workflow). This uses Serval's standard webhook trigger — no integration-specific setup:

<Steps>
  <Step title="Create a webhook-triggered workflow in Serval">
    Give your Serval workflow a **Webhook** trigger and copy its trigger URL (`/v2/webhooks/{webhook_id}/trigger`) and secret.
  </Step>

  <Step title="Create the outbound call in AlertOps">
    In AlertOps, either add a **Send Webhook** action to an AlertOps workflow, or create an **Outbound Integration** with a REST method. Point it at the Serval trigger URL.
  </Step>

  <Step title="Pass the secret">
    Add the secret as an `X-Webhook-Secret` header (or a `?secret=` query parameter) on the AlertOps side.
  </Step>

  <Step title="Shape the payload">
    Build the JSON body from AlertOps' dynamic fields (for example `<<MessageThread.Topic>>`, `<<Message.MessageText>>`) — whatever you send becomes the workflow's trigger payload.
  </Step>
</Steps>

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="The legacy v1 health check fails but v2 works">
    The v2 API documents the User API key from your profile. AlertOps' legacy v1 documentation predates that key and does not state whether older account-level keys differ from it. If only the legacy check fails, your key is valid for v2 but your account's v1 surface may expect a different key — contact AlertOps support if you need v1, or simply use the v2 equivalents (nearly every v1 endpoint has one).
  </Accordion>

  <Accordion title="Alert listings look incomplete">
    `GET /api/v2/alerts` defaults to `viewBy=U` (alerts visible to the key's user). Pass `viewBy: "A"` in the query to list all alerts the account allows, and note its date-range filters (createdFrom/createdTo, closedFrom/closedTo) are capped at six-month windows.
  </Accordion>

  <Accordion title="Two pagination styles in the v2 API">
    Most v2 list endpoints use integer `limit` (max 100) and `offset` with `sortBy`/`sortDir`. `GET /api/v2/alerts` instead uses cursor-style paging: string `limit`, plus `previous`/`next` cursors returned in the response's `metadata` envelope.
  </Accordion>

  <Accordion title="Alerts vs. incidents naming">
    `/api/v2/alerts` is the alerting/escalation surface (statuses: Open, Assigned, Closed, On Hold, Cancelled; `is_incident` flags major-incident management). `/api/v2/incidents` is the separate status-page surface (Investigating → Resolved) tied to `/api/v2/services` and subscriber notifications. Don't conflate them.
  </Accordion>

  <Accordion title="Response typing is loose">
    AlertOps' published v2 API spec does not describe response bodies, so v2 actions return untyped JSON (a few legacy v1 read endpoints, like listing topics or schedules, are typed). Consult the response examples in the AlertOps API portal ([https://api.alertops.com/help](https://api.alertops.com/help)) when mapping fields in your workflow.
  </Accordion>

  <Accordion title="Rate limits are unpublished">
    AlertOps documents no rate limits. If you build high-volume automation and see 429s or throttling symptoms, add pacing/retries in your workflow design.
  </Accordion>

  <Accordion title="A regenerated key breaks the connection immediately">
    Regenerating the API key in an AlertOps profile invalidates the old key instantly. Failed runs with 401 errors after someone touched the profile usually mean exactly this — paste the new key into the Serval connection settings.
  </Accordion>

  <Accordion title="Renaming an inbound integration's Source breaks its endpoint URL">
    The trailing segment of an inbound endpoint URL is the integration's **Source** value. Editing Source (or clicking Generate next to the URL) invalidates the old URL the moment the Rules drawer is saved — any workflow still passing the old source segment (or old token) to the send-inbound-alert action starts failing immediately. Update the action's inputs whenever someone rebrands an inbound integration.
  </Accordion>

  <Accordion title="Sent an inbound alert but no alert opened">
    Check the integration's **Inbound Log** in AlertOps (Configurations → the inbound integration → Inbound Log) and look at the message's mapping status. `Pending` can last up to a minute. `Mapping Failed` means the Source/Source Name in the URL and payload didn't match the integration's mapping fields. `Mapped Ignored` means the fields mapped but no alert was generated — either a close event arrived with no matching open alert, or the payload's status value isn't one the integration's Open/Close/Update rules recognize. Also remember the integration's filters may be intentionally dropping the event.
  </Accordion>
</AccordionGroup>

***

Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your AlertOps integration.