Developer guide

One request. A page that reaches the right phone.

A focused, server-side contract for sending urgent pages to Sevloom. Start with the request shape, test safely, then connect the same call to your monitoring or automation workflow.

Prerequisites

Set up Sevloom before you write the request.

You need a Sevloom Cloud account, a service, a paired device, and a service API key. Keep the key on your server or in a secret manager; never expose it in browser or mobile code.

1
Create your Sevloom account
Sign in to Sevloom Cloud, create or select a workspace, and create a service for the team or system that will send pages.
2
Download and pair the app
Install the Sevloom app, generate a pairing code from the service dashboard, and pair one or more responder devices.
3
Create an API key
Open the service API keys section, create a labeled key, and copy it once. Store it as SEVLOOM_API_KEY in your server environment.
4
Send a test page
Use one of the examples below from trusted server-side code and confirm that the page arrives on the paired device.

Send a page

Start with a complete request.

See the endpoint, authentication header, and request body together. Replace the placeholder API key with the key created in Sevloom Cloud.

Shell request

POST /v1/send

curl --request POST https://page.sevloom.com/v1/send \
  --header "X-Sevloom-API-Key: YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "severity": "sev2",
    "title": "Checkout API unavailable",
    "message": "5xx responses exceeded 20% for five minutes.",
    "source": "checkout-api",
    "environment": "production",
    "deduplicationKey": "checkout-api-5xx",
    "occurredAt": "2026-09-06T23:05:00.000Z",
    "metadata": { "region": "us-east-1", "runbookUrl": "https://example.com/runbooks/checkout-api" }
  }'

Request attributes

Reference the fields in one list.

Required attributes are listed first, followed by optional context fields.

severitystring

Requiredsev1, sev2, sev3, sev4, or sev5. The sender explicitly chooses urgency.

titlestring

RequiredA short description that is useful on a lock screen.

messagestring

RequiredWhat happened and the immediate context a responder needs.

deduplicationKeystring

RequiredA stable value used to group repeated reports of the same condition. Reuse it when retrying the same request.

sourcestring

OptionalThe service, monitor, application, or person that created the page. It defaults to Unknown source.

environmentstring

OptionalA recognizable label such as production, staging, or development.

occurredAtstring

OptionalAn ISO 8601 timestamp. Sevloom uses the receipt time when omitted or invalid.

metadataobject

OptionalUp to 32 short, non-sensitive scalar attributes such as a runbook URL, region, or trace ID.

Response

Read the accepted result.

A successful request returns an accepted page identifier and a request ID for tracing. The response does not echo the full request payload.

{
  "data": {
    "id": "page identifier",
    "status": "accepted",
    "deduplicated": false,
    "receivedAt": "2026-09-06T23:05:00.000Z"
  },
  "meta": {
    "apiVersion": "v1",
    "requestId": "request correlation ID"
  }
}

Errors

Know what to fix before retrying.

Use the HTTP status and request ID to diagnose failures. Retry only when the error is transient, and reuse the same deduplication key when retrying an uncertain request.

400Invalid requestA required field is missing or has an invalid value.

401UnauthorizedThe API key is missing, invalid, or no longer active.

404Not foundThe endpoint or service destination could not be found.

409ConflictThe request conflicts with an existing page or resource.

429Rate limitedToo many requests were received. Retry with backoff.

500Server errorThe request could not be completed. Use the request ID when contacting support.

Severity

The sender sets urgency; Sevloom delivers the page.

Severity is not inferred from the kind of error. A caller explicitly assigns SEV-1 through SEV-5 based on the response it needs. Every accepted request creates a page.

SEV-1

Immediate action

Use for an outage or condition where a delayed response materially increases impact.

SEV-2

Urgent response

Use for major degradation or a failed workflow that needs prompt attention.

SEV-3

Timely attention

Use for a meaningful issue that needs investigation without the strongest interruption.

SEV-4

Awareness

Use for a lower-urgency operational condition that is still worth seeing.

SEV-5

Informational

Use for context that should create a page without a pager sound.

Deduplication

Repeat the key, not the noise.

deduplicationKey is required. Reuse the same value when retrying after an uncertain network response or reporting the same condition. During the active deduplication window, Sevloom returns the existing page ID instead of creating a duplicate. Use a different stable key for a different condition. When the page corresponds to a ticket or incident, its stable identifier, such as INC-48291, is a good key.

Good keyINC-48291A ticket or incident ID stays stable across updates to the same issue.Also goodcheckout-api-5xxA stable monitor-condition identifier.Avoidcheckout-api-2026-09-06T23:05:00ZA timestamp makes every request look unrelated.

Page lifecycle

From accepted request to responder action.

The send endpoint returns accepted as a submission receipt because delivery is asynchronous. The page itself then follows the responder lifecycle: open until someone acknowledges it, then acknowledged. Sevloom records the page request, applies the deduplication key, and keeps each responder acknowledgement in the page history.

1. AcceptThe API validates the request and returns a page ID, status, receipt time, and request ID.2. DeduplicateA repeated request with the same key is associated with the existing condition instead of creating avoidable noise.3. DeliverThe page is routed to the service’s paired devices and its delivery state is recorded.4. AcknowledgeResponders acknowledge the page from the app; the page moves from open to acknowledged and each response is kept with the page history.