Developer Portal

What you can build with

• REST API — /api/v1: articles, feeds, countries, specs, sources.
• OpenAPI spec — /openapi.json: full schema, operation IDs, descriptions.
• NLWeb /ask — POST /ask: natural-language queries, JSON or SSE.
• MCP server card — /.well-known/mcp/server-card.json
• A2A agent card — /.well-known/agent-card.json
• Agent-skills index — /.well-known/agent-skills/index.json
• API catalog (RFC 9727) — /.well-known/api-catalog
• WebMCP — every page exposes navigator.modelContext tools.
• Markdown alternates — append .md or send Accept: text/markdown.
• RSS / JSON feeds — master, section, audience, country.

Quickstart

# Service index
curl https://peppolnews.com/api/v1

# 5 most recent mandate stories from Belgium
curl 'https://peppolnews.com/api/v1/articles?section=mandates&country=be&limit=5'

# One article
curl https://peppolnews.com/api/v1/articles/<slug>

# Markdown twin
curl -H 'Accept: text/markdown' https://peppolnews.com/2026/06/<slug>/

# Natural-language query (NLWeb)
curl -X POST https://peppolnews.com/ask \
  -H 'Content-Type: application/json' \
  -d '{"query":"What changed in Peppol BIS Billing 3 this quarter?"}'

# Streaming
curl -N -X POST https://peppolnews.com/ask \
  -H 'Content-Type: application/json' \
  -H 'Accept: text/event-stream' \
  -d '{"query":"Belgium mandate status","prefer":{"streaming":true}}'

Authentication

Reads are anonymous. For agents that prefer signed requests, the site publishes a Web Bot Auth directory at /.well-known/http-message-signatures-directory (RFC 9421 Ed25519 keys). For future write surfaces, OAuth Protected Resource Metadata lives at /.well-known/oauth-protected-resource and the full agent registration flow is documented in /auth.md.

Errors

JSON-shaped, never HTML:

{
  "error": {
    "code": "not_found",
    "message": "Article slug 'foo' not found",
    "hint": "List /api/v1/articles to discover valid slugs."
  }
}

Codes: not_found, bad_request, unauthorized, rate_limited, internal.

Webhooks

Subscribe to changes by POSTing your endpoint to /api/v1/webhooks:

curl -X POST https://peppolnews.com/api/v1/webhooks \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://your.app/peppolnews/webhook",
    "events": ["article.published", "article.corrected", "spec.updated"],
    "secret": "your-hmac-secret"
  }'

Events:

• article.published — new article landed.
• article.corrected — published article gained a correction.
• article.retracted — article was pulled.
• newsletter.sent — Weekly Brief went out.
• spec.updated — tracked Peppol spec changed.

Each delivery carries an X-PeppolNews-Signature HMAC-SHA256 header keyed by your secret over the raw body.

Sandbox

The live site is the sandbox. The read API is free and side-effect-free; no separate staging environment is required. The webhook subscription endpoint accepts a test=true flag that fires one synthetic event per registered topic against your URL.

SDKs

No official SDK is published yet. The OpenAPI spec at /openapi.json is compatible with openapi-generator-cli across npm, PyPI, Go modules, and RubyGems.

Support

Email desk@peppolnews.com for integration questions. Bug reports welcome.