# PeppolNews API

> Read-only JSON API over published articles, feeds, countries, and specs.

## Base URL

https://peppolnews.com/api/v1

## Authentication

No authentication required. All endpoints are public, read-only, and return JSON.
Unauthenticated requests to API roots return `401` with a `WWW-Authenticate: Bearer`
header pointing at the OAuth Protected Resource Metadata at
`https://peppolnews.com/.well-known/oauth-protected-resource` for future write surfaces. Reads
do not require credentials.

## Endpoints

- `GET /api/v1` — service index, lists available resources.
- `GET /api/v1/articles` — list articles. Query params: `section`, `audience`, `country`, `limit` (default 25, max 100), `offset`.
- `GET /api/v1/articles/{slug}` — one article with full metadata + sources.
- `GET /api/v1/feeds` — list of all RSS feeds (master, per-section, per-audience, per-country).
- `GET /api/v1/countries` — list of tracked countries with mandate status.
- `GET /api/v1/countries/{code}` — one country dossier.
- `GET /api/v1/specs` — list of tracked Peppol specs.
- `GET /api/v1/specs/{slug}` — one spec profile.
- `GET /api/v1/sources` — entries from the source registry (publishers we cite).
- `GET /openapi.json` — full OpenAPI 3.1 specification.

## Errors

All errors return JSON shaped `{ "error": { "code": "string", "message": "string", "hint": "string?" } }`
with a matching HTTP status. Codes used:

- `not_found` (404)
- `bad_request` (400)
- `unauthorized` (401)
- `rate_limited` (429)
- `internal` (500)

## Streaming

The NLWeb `/ask` endpoint supports SSE streaming. Send
`Accept: text/event-stream` or `prefer: streaming` to receive incremental
`start`, `result`, and `complete` events.

## Caching

Responses ship with edge cache headers (`max-age=300`, `s-maxage=3600`,
`stale-while-revalidate=86400`). Pass `Cache-Control: no-cache` to bypass.

## Webhooks

See https://peppolnews.com/developers#webhooks.