# PeppolNews Developer Portal

> Everything you need to integrate PeppolNews into an agent, app, or pipeline.

## What you can do

- Stream the news firehose (RSS, JSON Feed, NLWeb /ask).
- Fetch structured article metadata + sources via REST.
- Discover capabilities via MCP server card, A2A agent card, agent-skills index.
- Render Open Graph cards by article slug.
- Consume the markdown twin of any HTML page via `.md` suffix or
  `Accept: text/markdown`.

## Quickstart

```sh
# List the 25 most recent articles
curl -H 'Accept: application/json' https://peppolnews.com/api/v1/articles

# Fetch one article in JSON
curl https://peppolnews.com/api/v1/articles/<slug>

# Fetch the same article as markdown
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 variant
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

The read API is unauthenticated. For agent identification, the site supports
RFC 9421 HTTP Message Signatures via `/.well-known/http-message-signatures-directory`.
See https://peppolnews.com/auth.md for the full agent registration walkthrough.

## MCP

- Server card: https://peppolnews.com/.well-known/mcp/server-card.json
- WebMCP shim: every page loads `navigator.modelContext` tools in the browser.

## A2A

- Agent card: https://peppolnews.com/.well-known/agent-card.json

## SDKs

No official SDK published yet. The OpenAPI spec at https://peppolnews.com/openapi.json is
generator-ready (try `openapi-generator-cli`).

## Webhooks

POST your endpoint to `/api/v1/webhooks` (see /developers#webhooks). Events:
`article.published`, `article.corrected`, `article.retracted`,
`newsletter.sent`, `spec.updated`.

## Rate limits

None enforced beyond Cloudflare edge defaults. Be polite.

## Sandbox

The live site is the sandbox: it's read-only and free. There is no separate
staging environment for agents.

## Status

- Health: https://peppolnews.com/api/v1
- Sitemap: https://peppolnews.com/sitemap-index.xml
- News sitemap: https://peppolnews.com/news-sitemap.xml