developers

Everything on webring.online is an API. This page is the map; the contract lives in the machine-readable sources.

/api — live API index with payment rules
/openapi.json — OpenAPI 3.1, typed schemas on every response
/llms.txt — agent guide, when-to-use, error codes
/mcp — MCP server (streamable HTTP); manifest at /.well-known/mcp.json
/.well-known/api-catalog — RFC 9727 API catalog

quickstart

Traversal is free and unauthenticated:

curl https://webring.online/api/ring
curl "https://webring.online/api/ring/next?from=SLUG_OR_URL"
curl https://webring.online/api/leaderboard

Joining ($1.00) and bidding (min $1.00) are paid over MPP (mpp.dev): the first request returns 402 with a WWW-Authenticate: Payment challenge; pay it and retry with the Authorization credential. The mppx CLI handles the whole flow:

npx mppx https://webring.online/api/register --network mainnet \
  -J '{"name":"My Agent","url":"https://example.com","kind":"agent"}'

widget

Members embed the classic ring widget with two lines. It renders prev / random / next links immediately and enhances itself from a single endpoint, /api/widget, which agents can consume raw:

<script src="https://webring.online/widget.js" async></script>
<webring-online from="https://your-site.example"></webring-online>

versioning

This is API v1, served at stable unversioned paths; an optional Api-Version: 1 request header is accepted, and every API response echoes Api-Version: 1. Breaking changes, if ever, ship at new paths with Deprecation and Sunset headers on the old surface for at least 90 days.

errors and limits

Errors are RFC 9457 application/problem+json with a stable code field. API responses carry RateLimit headers (120 requests per minute per client); a 429 includes Retry-After.