How to send a page

Four intake paths

Pick one path per source. Credentials are not interchangeable: an API key authenticates JSON and email ingest; an Alertmanager ingest token authenticates the webhook. Wrong-type bearers fail closed.

REST API — team API key

Create a team key in the app (API keys — team admin or org admin). The secret is shown once. A team key is create-only and bound to exactly one team: it can raise a page to that team, and cannot read, acknowledge, or reach any other team.

• Endpoint: POST /alerts with Authorization: Bearer <api-key-secret>
• Body includes a team target, summary, optional description, and criticality (normal or critical)
• Cross-team retargets return a uniform not-found — a team key cannot escape its bound team

Example — raise a critical page to a team
curl -sS -X POST "https://terranpage.com/alerts" \
  -H "Authorization: Bearer ${API_KEY_SECRET}" \
  -H "Content-Type: application/json" \
  -d '{
    "target": { "type": "team", "team_id": "t_…" },
    "summary": "Disk full on db-01",
    "description": "filesystem /var at 98%",
    "criticality": "critical"
  }'

REST API — personal API key

Create a personal key in the app (API keys — any org member, no admin role needed). The secret is shown once. A personal key is create-only and carries no team binding: it can page you directly, or any team you currently belong to, and cannot target another person.

• Endpoint: POST /alerts with Authorization: Bearer <api-key-secret>
• Self-target: { "type": "user", "user_id": "<your user id>" } — find it under your profile
• Team target: { "type": "team", "team_id": "t_…" } — allowed only for a team you belong to

Example — page yourself
curl -sS -X POST "https://terranpage.com/alerts" \
  -H "Authorization: Bearer ${API_KEY_SECRET}" \
  -H "Content-Type: application/json" \
  -d '{
    "target": { "type": "user", "user_id": "u_…" },
    "summary": "Backup job failed",
    "criticality": "normal"
  }'

Prometheus Alertmanager webhook

Point Alertmanager at TerranPage with a native webhook — no translation shim. The ingest token is bound to one team at issuance; the payload cannot re-target. Tokens are issued for your organization on request (they are not self-serve in the app today).

• Endpoint: POST /ingest/alertmanager with Authorization: Bearer <ingest-token>
• Uses Alertmanager's webhook shape, including groupKey dedup and status: resolved auto-close
• Rate-limited per token; excess returns 429 with an observable suppression (never a silent drop)

Example — Alertmanager receiver
receivers:
  - name: terranpage
    webhook_configs:
      - url: https://terranpage.com/ingest/alertmanager
        http_config:
          authorization:
            type: Bearer
            credentials: "<ingest-token-secret>"
        send_resolved: true

Need an ingest token for your org? Contact us — we mint and rotate it for you.

Email ingest

Every API key gets a private ingest address. Mail from a verified, allow-listed sender that passes industry-standard authentication checks becomes an alert on the bound team. Anything else is rejected and recorded in that key's ingest audit.

• Same API key credential family as the REST path — do not publish the token local-part
• Manage accepted senders in the app under the key that owns the address

Manual page

From the web console or iOS app, use "Start a page" to raise an alert to a team or a person — normal or critical — without a machine credential. Useful for drills and human-driven escalation.