webcentive.com | API | MCP | openapi.json

Webcentive API

Read-only JSON API for Webcentive Today News and category lists. No authentication. Machine-readable contract: /openapi.json (OpenAPI 3.1). MCP tools: Webcentive MCP server.

Versioning

Current major version is 1, exposed under /api/v1/ and in the API-Version: 1 response header. Legacy CGI paths remain available but are documented as deprecated in OpenAPI. When a major version will be removed, responses gain Deprecation (RFC 9745) and Sunset (RFC 8594) headers with a calendar date, and this page is updated. Minimum notice: 90 days before a major version or documented field is removed.

Endpoints

• GET /api/v1/news?cat=<slug> — Today News JSON for one category
• GET /api/v1/categories — list public todaynews category slugs
• POST /api/mcp — MCP Streamable HTTP (also /.well-known/mcp)

Rate limits

Per client IP (hashed on disk under the account ~/var/ratelimit/, no sudo). Default: about 60 requests / 60 seconds for news and MCP, 120 / 60s for categories. Responses include RateLimit-Policy and RateLimit (IETF httpapi-ratelimit-headers style). When exceeded: HTTP 429, Retry-After, and JSON {"error":{"code":"rate_limited","message":"...","hint":"..."}}.

curl examples

curl -sS 'https://www.webcentive.com/api/v1/categories' | head -c 200
curl -sS 'https://www.webcentive.com/api/v1/news?cat=firewalls' | head -c 200
curl -sS -D - -o /dev/null 'https://www.webcentive.com/api/v1/news?cat=firewalls' | grep -iE 'API-Version|RateLimit'

Errors

JSON errors use {"error":{"code","message","hint"}} with 4xx/5xx status.

CLI

A dependency-free POSIX shell CLI (curl only) is published at /cli/webcentive (SHA-256 on that page). It is not an npm/PyPI/Homebrew package.

Operator: Antonio Casanova — contact. United States.