# PeppolStatus API — quickstart for agents

Public, read-only REST API for PeppolStatus.com: open-data monitoring of the Peppol
e-invoicing network — host liveness, incidents, participants, providers, seats,
change events, anomalies, SML/SMK zone status and network rollups.

- **Base URL:** `https://api.peppolstatus.com`
- **Machine-readable spec:** [OpenAPI 3.1](https://api.peppolstatus.com/openapi.json)
- **Human docs:** [Scalar UI](https://api.peppolstatus.com/docs)
- **Liveness:** `GET /health` → `{"status":"ok","service":"api"}` · DB check: `GET /health/db`
- **Methods:** GET/HEAD/OPTIONS only. All responses are JSON; errors use RFC 9457 `application/problem+json`.

## Authentication

None required. Every endpoint is public and read-only.

A free account at [app.peppolstatus.com/sign-up](https://app.peppolstatus.com/sign-up)
issues an API key instantly (format `pps_live_…` / `pps_test_…`), managed at
[app.peppolstatus.com/keys](https://app.peppolstatus.com/keys) and sent as
`Authorization: Bearer <key>`. Today keys are optional and used for attribution and
rate-limit purposes, with paid tiers to come. There is no OAuth/OIDC server and no
dynamic client registration. Details: [/auth.md](https://peppolstatus.com/auth.md).

## Endpoint families (all under /v1)

| Family | Endpoints | What it returns |
|---|---|---|
| Network | `/v1/network` | At-a-glance rollup: host verdict counts, open incidents, anomalies in the last 24h. |
| Hosts | `/v1/hosts`, `/v1/hosts/{hostname}`, `…/incidents`, `…/uptime` | Monitored SMP/AP hosts: current verdict, latency, 24h uptime; per-host incidents and uptime aggregates (hourly/daily/monthly). |
| Incidents | `/v1/incidents` | Global incident feed (open/closed), newest-first. |
| Participants | `/v1/participants`, `/v1/participants/{id}`, `…/events`, `…/history` | Peppol participants: filterable list, current state, change events, temporal history. |
| Participant stats | `/v1/stats/participants` | Global facet counts (country/scheme/SMP/AP, registered share, provenance) plus estimated total. |
| Providers | `/v1/providers`, `/v1/providers/{slug}` | OpenPeppol member registry and curated provider detail. |
| Access points | `/v1/aps`, `/v1/aps/{key}`, `…/churn`, `…/churn/participants` | AP directory with rosters; churn (joiners, movers in/out, leavers) per AP. |
| Seats | `/v1/seats/{seatId}` | Certificate seats — the machine identity of a provider. |
| Events | `/v1/events` | Global typed change-event feed (registrations, migrations, cert rotations, …) with embedded anomalies. |
| Anomalies | `/v1/anomalies`, `/v1/anomalies/{id}` | Deterministic detector anomalies, graded notice/warning. |
| SML | `/v1/sml` | SML/SMK zone canary status and DNAME cutover state. |

## Conventions

- **Pagination:** list endpoints are cursor-paginated — `{ "items": [...], "next_cursor": "..." }`; pass `cursor` (and optionally `limit`) to walk pages. `/v1/events` also supports `prev_cursor` for live polling of the newer edge.
- **Participant IDs:** canonical `scheme::value`, e.g. `0208::0762747721`.
- **Rate limit:** 60 requests / 60s per client identity; `RateLimit-*` headers on every response.

## Examples

```sh
# Network-wide rollup
curl https://api.peppolstatus.com/v1/network

# Newest Belgian participants, 5 per page
curl "https://api.peppolstatus.com/v1/participants?country=BE&limit=5"

# One participant's current state (scheme::value)
curl "https://api.peppolstatus.com/v1/participants/0208::0762747721"
```

## Versioning & deprecation

The API is versioned in the URL path (`/v1`). Backwards-incompatible changes
only ship under a new version prefix — existing `/v1` response shapes are
additive-only. If an endpoint is ever scheduled for removal, it will be
announced here and in the OpenAPI description first, and signaled with
`Deprecation` and `Sunset` response headers before it goes away. Nothing is
deprecated today.

## CORS

`Access-Control-Allow-Origin: *` — call the API directly from browsers and web apps.

## Discovery

- API catalog (RFC 9727): [/.well-known/api-catalog](https://peppolstatus.com/.well-known/api-catalog)
- Agent skills: [/.well-known/agent-skills/index.json](https://peppolstatus.com/.well-known/agent-skills/index.json)
- Auth details: [/auth.md](https://peppolstatus.com/auth.md)

Questions: [hello@peppolstatus.com](mailto:hello@peppolstatus.com). PeppolStatus is built by [e-invoice.be](https://e-invoice.be).