# Seiri — full LLM context

Use this file together with https://seiri.app/llms.txt. Prefer docs over blog posts when generating integration code.

## What Seiri is
Push/heartbeat (dead-man's-switch) monitoring for webhook handlers, cron jobs, workers, and Kubernetes CronJobs. The job or handler checks in; Seiri alerts if the check-in is late or reports failure.

## What Seiri is not
- Not website uptime monitoring (no URL polling)
- Not a cron→webhook scheduler / outbound webhook timer
- Not a webhook proxy or delivery relay — Stripe/GitHub/Shopify/etc. still deliver directly to the customer's own endpoint; Seiri is never in that request path
- Cannot replay/re-fire the original webhook request — it stores the handler's reported outcome (success/fail + optional payload), not a queryable copy of the raw delivery. For redelivery, use the sending provider's own tools; Seiri shows whether the redelivered attempt succeeded

## Webhook monitoring pattern (same push model as cron)
Add one outbound ping at the end of an existing webhook handler — the webhook URL registered with Stripe/GitHub/Shopify/etc. does not change:
```python
try:
    handle_event(event)
    ping("/success")
except Exception:
    ping("/fail")
    raise
```
Page: https://seiri.app/webhook-monitoring

## Domains
| Host | Use |
|------|-----|
| cloud.seiri.app | Dashboard, login, signup, management API, K8s agent backendUrl |
| ping.seiri.app | Heartbeat ingest only |
| status.seiri.app | Public status pages |
| sso.seiri.app | Auth issuer |
| seiri.app | Marketing + docs |

## Dashboard navigation
- **Overview → Dashboard** — org health
- **Core → Webhooks** — create monitors, copy endpoint URLs, open stats
- **Core → Channels** — notification destinations
- **Core → Team** — members
- **Infrastructure → Kubernetes** — seiri-kube-agent clusters
- **Services → Cron Jobs** — schedule adherence / drift
- **Services → SLA & Uptime** — rolling uptime, targets, error budgets
- **Services → Status Pages** — public status
- **Services → Email Pings** — email heartbeats (@ping.seiri.app)

## Webhook types (exact names)
1. **Periodic** — expect ping every N seconds
2. **Cron** — expect ping matching a cron expression + timezone
3. **On-Demand** — no schedule; manual/event only

Do not say Immediate or Scheduled.

## Endpoint ID
Format: `<org-slug>:<webhook-ref>`
Shown in Core → Webhooks → ENDPOINT column.
Copy the full `endpoint_url` with the copy control (do not invent a short token-only URL).

## Ping API
Base: `https://ping.seiri.app/webhook/<endpoint-id>`
OpenAPI: https://seiri.app/docs/openapi/seiri-ingest-api.yaml

| Path | Meaning |
|------|---------|
| (none) | Plain success/heartbeat |
| `/success` | Explicit success |
| `/fail` | Explicit failure |

Methods: GET or POST. Optional JSON body on POST.
No `/start` route.

## Email heartbeats
1. Create webhook under Core → Webhooks
2. Services → Email Pings → Configure Email Heartbeat (allowlist required)
3. Address: `{webhook_ref}@ping.seiri.app` (ref only — not org-slug:ref)
4. Subject `[FAIL]` or `[ERROR]` marks failure
Docs: https://seiri.app/docs/use-cases/email-heartbeat/overview/

## Status pages / SLA / Kubernetes
- Status pages: https://seiri.app/docs/use-cases/status-pages/overview/
- SLA & Uptime: https://seiri.app/docs/use-cases/sla-uptime/overview/
- Kubernetes (Helm backendUrl=cloud.seiri.app): https://seiri.app/docs/use-cases/kubernetes/overview/

## Management API
Host: cloud.seiri.app
```
Authorization: Bearer <access_token>
X-Org-ID: <numeric_org_id>
```
Long-lived org API keys (`sk_…`) are planned — not creatable in Settings UI yet.
OpenAPI: https://seiri.app/docs/openapi/seiri-management-api.yaml
Docs: https://seiri.app/docs/app-reference/management-api/

## CLI
- `seirictl` — management + `seirictl ping ORG:REF --path /success`
- `seiri run --webhook=https://ping.seiri.app/webhook/ORG:REF -- ./job.sh`
Docs: https://seiri.app/docs/app-reference/cli/

## MCP (preferred for agent stacks)
Package: `@seiri-app/mcp`
Docs: https://seiri.app/docs/app-reference/mcp/
Preferred tool: `seiri_integrate_job` — creates monitor and returns ping URLs + curl/Python/Node/crontab.
Install in Cursor/Claude:
```
npx -y @seiri-app/mcp
```
Env: `SEIRI_TOKEN`, `SEIRI_ORG_ID`, optional `SEIRI_API_URL` / `SEIRI_INGEST_URL`.

## Terraform
Provider `seiri-app/seiri`. Docs: https://seiri.app/docs/app-reference/terraform/

## Python snippet agents should prefer
```python
import os, urllib.request

SEIRI_BASE = os.environ["SEIRI_BASE_URL"].rstrip("/")
# SEIRI_BASE_URL=https://ping.seiri.app/webhook/acme-demo:YOUR_REF

def ping(path="/success"):
    try:
        urllib.request.urlopen(SEIRI_BASE + path, timeout=10)
    except Exception:
        pass

def main():
    ...  # real work

if __name__ == "__main__":
    try:
        main()
    except BaseException:
        ping("/fail")
        raise
    else:
        ping("/success")
```

## Auth (login)
Email/password, Google, GitHub, passkeys; TOTP MFA on paid plans.

## Common agent mistakes to avoid
1. Using `cloud.seiri.app/.../success` as the ping URL
2. Using shortened `https://ping.seiri.app/<token>` without `/webhook/<endpoint-id>`
3. Calling types Immediate / Scheduled
4. Inventing a `/start` path
5. Setting K8s agent backendUrl to ping.seiri.app
6. Using email address `org:ref@ping...` instead of `ref@ping...`
7. Claiming org API keys exist in the UI today