Immediate action
Use for an outage or condition where a delayed response materially increases impact.
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 circle, a paired device, and a service API key. Every request must include both the API key and the matching circle ID. Keep both values on your server or in a secret manager; never expose them in browser or mobile code.
- 1Create your Sevloom account
Sign in to Sevloom Cloud, create or select a workspace, and create a circle for the system that will send pages.
- 2Download and pair the app
Install the Sevloom app, generate a pairing code from the service dashboard, and pair one or more responder devices.
- 3Create an API key
Open the circle API keys section, create a labeled key, and copy it once. Store it as
SEVLOOM_API_KEYin your server environment. Store the matching circle ID asSEVLOOM_CIRCLE_ID. - 4Send 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, both required authentication headers, and the request body together. Replace the placeholder API key and circle ID with values from 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 "X-Sevloom-Circle-ID: svc_YOUR_CIRCLE_ID" \
--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. The circle ID is supplied in the X-Sevloom-Circle-ID header, not in the JSON body.
severitystringtitlestringmessagestringdeduplicationKeystringsourcestringenvironmentstringoccurredAtstringmetadataobjectResponse
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.
Urgent response
Use for major degradation or a failed workflow that needs prompt attention.
Timely attention
Use for a meaningful issue that needs investigation without the strongest interruption.
Awareness
Use for a lower-urgency operational condition that is still worth seeing.
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 key
INC-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.