# Events API

> Any language that can make an HTTPS request can send to Pagerless. The SDKs use this same API.

URL: https://pagerless.dev/docs/events-api
Updated: 2026-10-22

```bash
curl -X POST https://events.pagerless.dev/v1/events \
  -H "Authorization: Bearer $PAGERLESS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"events":[{"v":1,"id":"evt_2026_10_22_0001","type":"error","ts":'$(date +%s000)',"service":"api","route":"POST /checkout","status":500,"error":{"type":"StripeError","message":"card_declined rate spike"}}]}'
```

A valid batch returns `202`. A missing or wrong key returns `401`.

## Endpoints

| Path | Body |
| --- | --- |
| `POST /v1/events` | `{"events": [...]}`, 1 to 500 events |
| `POST /v1/heartbeat` | `{"service", "env", "release"}` or `?service=` |
| `POST /v1/checkins/<job>` | Empty means ok. See [check-ins](https://pagerless.dev/docs/check-ins). |
| `POST /v1/otlp/v1/logs`, `/v1/otlp/v1/traces`, `/v1/otlp/v1/metrics` | OTLP over HTTP, protobuf or JSON. See [OpenTelemetry](https://pagerless.dev/docs/opentelemetry). |
| `POST /v1/hooks/<tool>/<key>` | Alerts from 14 monitoring tools. See [alert sources](https://pagerless.dev/integrations#alert-sources). |
| `POST /v1/aws/sns` | SNS notifications. See [CloudWatch](https://pagerless.dev/integrations/aws-cloudwatch). |

## Event fields

| Field | Required | Meaning |
| --- | --- | --- |
| `v` | yes | Always `1` |
| `id` | yes | 8 to 64 characters; the idempotency key (a retry with the same id counts once) |
| `type` | yes | `error`, `metric`, `heartbeat`, `deploy`, `custom`, `resolve` or `checkin` |
| `ts` | yes | Unix time in milliseconds |
| `service` | yes | Which service, for example `api` |
| `env` | no | Default `production` |
| `release` | no | Commit or version; lets the AI connect errors to a deploy |
| `route`, `status` | no | `POST /checkout`, `500` |
| `error` | no | `{type, message, stack?}` |
| `fingerprint` | no | Your own grouping key; computed if missing |
| `count`, `window_s` | no | Pre-aggregated count over a window |
| `metric` | no | `{name, value, unit?}` |
| `severity`, `title` | no | For `custom` events: `wake`, `tell` or `log` |
| `tags` | no | String map |

## Auth and limits

- `Authorization: Bearer <ingest key>`. Keys look like `pl_live_` plus 32 hex characters and can only write.
- 1 MB per request, 500 events per batch, 600 requests per minute per key (`429` with `retry-after`).
- CORS is open, so the browser SDK can send directly.