{ "openapi": "3.1.0", "info": { "title": "PeppolNews API", "version": "1.0.0", "summary": "Read-only JSON API over Peppol and e-invoicing news, feeds, countries, specs, and the source registry.", "description": "Public, anonymous, read-only HTTP API serving PeppolNews content. All endpoints return JSON. Errors follow a uniform `{ error: { code, message, hint? } }` shape. Free; no API key.\n\n**Versioning & deprecation.** The API is versioned in the URL path (`/api/v1`). Breaking changes ship under a new path (`/api/v2`); a retired version keeps serving while returning `Deprecation` and `Sunset` response headers for at least six months before removal.\n\n**Rate limits.** Responses carry IETF `RateLimit`/`RateLimit-Policy` headers (plus the legacy `RateLimit-Limit`/`-Remaining`/`-Reset` fields) advertising a nominal 1000-request / 60-second ceiling so agents can self-throttle; a `429` carries `Retry-After`.\n\n**Idempotency.** Write operations accept an `Idempotency-Key` request header so a retried POST is applied at most once.", "contact": { "name": "PeppolNews desk", "email": "desk@peppolnews.com", "url": "https://peppolnews.com/contact" }, "license": { "name": "Editorial © PeppolNews; API access free", "url": "https://peppolnews.com/terms" }, "termsOfService": "https://peppolnews.com/terms" }, "externalDocs": { "description": "Developer portal", "url": "https://peppolnews.com/developers" }, "servers": [ { "url": "https://peppolnews.com/api/v1", "description": "Production" } ], "tags": [ { "name": "Articles", "description": "Published news articles." }, { "name": "Feeds", "description": "RSS / JSON feed catalog." }, { "name": "Countries", "description": "Tracked countries and mandate status." }, { "name": "Specs", "description": "Tracked Peppol specifications." }, { "name": "Sources", "description": "Source registry of publishers we cite." }, { "name": "Webhooks", "description": "Event subscriptions." }, { "name": "Auth", "description": "Agent authentication (register, claim, revoke)." }, { "name": "NLWeb", "description": "Natural-language ask endpoint." } ], "paths": { "/": { "get": { "operationId": "getServiceIndex", "summary": "Service index", "description": "Top-level service index listing available resources, auth posture, and discovery URLs.", "tags": [ "Articles" ], "responses": { "200": { "description": "Service index", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceIndex" } } } } } } }, "/articles": { "get": { "operationId": "listArticles", "summary": "List articles", "description": "List published English-canonical articles. Supports filtering by section, audience, country.", "tags": [ "Articles" ], "parameters": [ { "name": "section", "in": "query", "schema": { "type": "string", "enum": [ "mandates", "network", "vendors", "policy", "specs", "guides" ] } }, { "name": "audience", "in": "query", "schema": { "type": "string", "enum": [ "biz", "ap", "vendor", "policy" ] } }, { "name": "country", "in": "query", "schema": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2, lowercase." } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "Article list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArticleList" } } } } } } }, "/articles/{slug}": { "get": { "operationId": "getArticle", "summary": "Get one article", "description": "Fetch one article by slug.", "tags": [ "Articles" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Article", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Article" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/feeds": { "get": { "operationId": "listFeeds", "summary": "List feeds", "description": "List all RSS / JSON feeds available across sections, audiences, countries, and the newsletter.", "tags": [ "Feeds" ], "responses": { "200": { "description": "Feed catalog", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedCatalog" } } } } } } }, "/countries": { "get": { "operationId": "listCountries", "summary": "List countries", "description": "List tracked countries with mandate status.", "tags": [ "Countries" ], "responses": { "200": { "description": "Country list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountryList" } } } } } } }, "/countries/{code}": { "get": { "operationId": "getCountry", "summary": "Get one country dossier", "tags": [ "Countries" ], "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 2 } } ], "responses": { "200": { "description": "Country dossier", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Country" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/specs": { "get": { "operationId": "listSpecs", "summary": "List specs", "description": "List tracked Peppol specifications.", "tags": [ "Specs" ], "responses": { "200": { "description": "Spec list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpecList" } } } } } } }, "/specs/{slug}": { "get": { "operationId": "getSpec", "summary": "Get one spec", "tags": [ "Specs" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Spec", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Spec" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/sources": { "get": { "operationId": "listSources", "summary": "List sources", "description": "List entries from the source registry — publishers we cite.", "tags": [ "Sources" ], "responses": { "200": { "description": "Source list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceList" } } } } } } }, "/webhooks": { "get": { "operationId": "describeWebhooks", "summary": "Describe webhook events", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Webhook catalog", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCatalog" } } } } } }, "post": { "operationId": "createWebhookSubscription", "summary": "Subscribe to webhook events", "tags": [ "Webhooks" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url", "events" ], "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } }, "secret": { "type": "string", "description": "HMAC-SHA256 secret used to sign deliveries." } } } } } }, "responses": { "201": { "description": "Subscription created" }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer realm=\"peppolnews\", resource_metadata=\"https://peppolnews.com/.well-known/oauth-protected-resource\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/agent-auth/register": { "get": { "operationId": "describeAgentRegister", "summary": "Describe the agent registration endpoint", "tags": [ "Auth" ], "responses": { "200": { "description": "Registration endpoint descriptor", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "post": { "operationId": "registerAgent", "summary": "Register an agent client", "description": "Obtain a client_id and registration access token (auth.md agent_auth.register_uri).", "tags": [ "Auth" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "client_name" ], "properties": { "client_name": { "type": "string" }, "contact": { "type": "string", "format": "email" }, "identity_type": { "type": "string", "enum": [ "anonymous", "identity_assertion" ] }, "assertion_types_supported": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "201": { "description": "Client registered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRegistration" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent-auth/claim": { "post": { "operationId": "claimAgentToken", "summary": "Exchange an identity assertion for an access token", "description": "Claim a bearer access token (auth.md agent_auth.claim_uri).", "tags": [ "Auth" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "grant_type", "client_id" ], "properties": { "grant_type": { "type": "string", "default": "urn:ietf:params:oauth:grant-type:identity-assertion" }, "identity_assertion": { "type": "string", "description": "An id-jag token." }, "client_id": { "type": "string" } } } } } }, "responses": { "200": { "description": "Access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessToken" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent-auth/revoke": { "post": { "operationId": "revokeAgentToken", "summary": "Revoke a token (RFC 7009)", "tags": [ "Auth" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "token" ], "properties": { "token": { "type": "string" }, "token_type_hint": { "type": "string", "enum": [ "access_token", "refresh_token" ] } } } } } }, "responses": { "200": { "description": "Token revoked (empty body on success)." } } } }, "/ask": { "post": { "operationId": "ask", "summary": "Natural-language query (NLWeb)", "description": "POST a natural-language query against the published corpus. Returns JSON by default; SSE when Accept: text/event-stream.", "tags": [ "NLWeb" ], "servers": [ { "url": "https://peppolnews.com", "description": "Site root (NLWeb /ask is mounted there, not under /api/v1)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string" }, "locale": { "type": "string", "default": "en" }, "prefer": { "type": "object", "properties": { "streaming": { "type": "boolean" } } } } } } } }, "responses": { "200": { "description": "Answer (JSON) or SSE stream when Accept: text/event-stream.", "content": { "application/json": { "schema": { "type": "object" } }, "text/event-stream": { "schema": { "type": "string" } } } } } } } }, "components": { "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Client-supplied unique key so a retried write is applied at most once. Reuse the same key when retrying a POST after a network failure.", "schema": { "type": "string", "maxLength": 255 } } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Bearer token issued by the agent-auth flow. See /auth.md." } }, "schemas": { "ServiceIndex": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "description": { "type": "string" }, "base_url": { "type": "string", "format": "uri" }, "resources": { "type": "array", "items": { "type": "object" } } } }, "Article": { "type": "object", "properties": { "slug": { "type": "string" }, "title": { "type": "string" }, "kicker": { "type": "string", "nullable": true }, "dek": { "type": "string", "nullable": true }, "section": { "type": "string" }, "audience": { "type": "array", "items": { "type": "string" } }, "countries": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "locale": { "type": "string" }, "published_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time", "nullable": true }, "sources": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string", "format": "uri" } } } }, "url": { "type": "string", "format": "uri" }, "markdown_url": { "type": "string", "format": "uri" }, "og_image": { "type": "string", "format": "uri" } }, "required": [ "slug", "title", "section", "audience", "countries", "published_at", "sources", "url" ] }, "ArticleList": { "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "nullable": true }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Article" } } } }, "Country": { "type": "object", "properties": { "code": { "type": "string", "minLength": 2, "maxLength": 2 }, "name": { "type": "string" }, "mandate_status": { "type": "string" }, "authority": { "type": "string", "nullable": true }, "url": { "type": "string", "format": "uri" } }, "required": [ "code", "name" ] }, "CountryList": { "type": "object", "properties": { "count": { "type": "integer" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Country" } } }, "required": [ "count", "items" ] }, "Spec": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string", "nullable": true }, "last_changed": { "type": "string", "format": "date-time", "nullable": true }, "url": { "type": "string", "format": "uri" } }, "required": [ "slug", "name" ] }, "SpecList": { "type": "object", "properties": { "count": { "type": "integer" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Spec" } } }, "required": [ "count", "items" ] }, "Source": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "homepage": { "type": "string", "format": "uri" }, "trust_tier": { "type": "string" } }, "required": [ "slug", "name" ] }, "SourceList": { "type": "object", "properties": { "count": { "type": "integer" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Source" } } }, "required": [ "count", "items" ] }, "Feed": { "type": "object", "properties": { "title": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "type": { "type": "string", "enum": [ "rss", "json" ] } }, "required": [ "url" ] }, "FeedCatalog": { "type": "object", "properties": { "count": { "type": "integer" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Feed" } } }, "required": [ "items" ] }, "WebhookCatalog": { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "string" } }, "registration_url": { "type": "string", "format": "uri" }, "signing": { "type": "string", "description": "HMAC-SHA256 over the raw body." } }, "required": [ "events" ] }, "AgentRegistration": { "type": "object", "properties": { "client_id": { "type": "string" }, "registration_access_token": { "type": "string" }, "claim_uri": { "type": "string", "format": "uri" }, "revocation_uri": { "type": "string", "format": "uri" } }, "required": [ "client_id" ] }, "AccessToken": { "type": "object", "properties": { "access_token": { "type": "string" }, "token_type": { "type": "string", "default": "Bearer" }, "expires_in": { "type": "integer" }, "scope": { "type": "string" } }, "required": [ "access_token", "token_type" ] }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "not_found", "bad_request", "unauthorized", "rate_limited", "internal" ] }, "message": { "type": "string" }, "hint": { "type": "string" } }, "required": [ "code", "message" ] } } } } } }