{ "openapi": "3.1.0", "info": { "title": "webring.online", "version": "1.0.0", "description": "A pay-to-join webring for the agentic web. Registration ($1.00) and leaderboard bids (min $1.00, no increments) are paid over MPP (Machine Payments Protocol): request without payment, receive 402 + WWW-Authenticate: Payment, pay, retry with the Authorization credential. Registration requires an is-agentic.com score of at least 40. Errors are RFC 9457 application/problem+json with a stable machine-readable code. An MCP server (streamable HTTP) mirrors the read surface at /mcp.\n\nVersioning: this is v1, served at these stable unversioned paths; the optional Api-Version request header (current value: 1) is accepted and every response echoes Api-Version. Breaking changes, if ever, ship at new paths; the old surface then carries Deprecation and Sunset headers for at least 90 days before removal.\n\nRate limits: 120 requests per minute per client, advertised via RateLimit-Policy, RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset response headers; a 429 carries Retry-After." }, "servers": [ { "url": "https://webring.online" } ], "paths": { "/api": { "get": { "operationId": "getApiIndex", "summary": "API index", "responses": { "200": { "description": "Directory of endpoints and payment rules." }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ] } }, "/api/ring": { "get": { "operationId": "listRing", "summary": "List ring members in ring order (paginated)", "parameters": [ { "name": "kind", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "agent", "mcp", "website" ] } }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "1-based alternative to offset; offset wins when both are present." }, { "$ref": "#/components/parameters/ApiVersion" } ], "responses": { "200": { "description": "A page of members in ring order.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberList" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/ring/next": { "get": { "operationId": "nextMember", "summary": "Next member around the ring (wraps)", "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Member slug, member URL, or bare hostname to traverse from. Omitted: enters the ring at its edge." }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "agent", "mcp", "website" ] } }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "redirect" ] }, "description": "format=redirect responds 302 to the member site instead of JSON." }, { "$ref": "#/components/parameters/ApiVersion" } ], "responses": { "200": { "description": "The member.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Traversal" } } } }, "302": { "description": "With format=redirect: redirect to the member site." }, "404": { "description": "Unknown from reference, or empty ring.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/ring/prev": { "get": { "operationId": "prevMember", "summary": "Previous member around the ring (wraps)", "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Member slug, member URL, or bare hostname to traverse from. Omitted: enters the ring at its edge." }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "agent", "mcp", "website" ] } }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "redirect" ] }, "description": "format=redirect responds 302 to the member site instead of JSON." }, { "$ref": "#/components/parameters/ApiVersion" } ], "responses": { "200": { "description": "The member.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Traversal" } } } }, "302": { "description": "With format=redirect: redirect to the member site." }, "404": { "description": "Unknown from reference, or empty ring.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/ring/random": { "get": { "operationId": "randomMember", "summary": "Random member", "parameters": [ { "name": "kind", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "agent", "mcp", "website" ] } }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "redirect" ] }, "description": "format=redirect responds 302 to the member site instead of JSON." }, { "$ref": "#/components/parameters/ApiVersion" } ], "responses": { "200": { "description": "The member.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Traversal" } } } }, "302": { "description": "With format=redirect: redirect to the member site." }, "404": { "description": "Unknown from reference, or empty ring.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/ring/{slug}": { "get": { "operationId": "getMember", "summary": "One member, with leaderboard rank", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ApiVersion" } ], "responses": { "200": { "description": "Member detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberDetail" } } } }, "404": { "description": "Unknown member.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/categories": { "get": { "operationId": "listCategories", "summary": "Categories in use", "responses": { "200": { "description": "Category list with counts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategoryList" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ] } }, "/api/widget": { "get": { "operationId": "getWidget", "summary": "One-call widget payload: member, neighbors, and traversal links", "description": "Backs the embeddable element served at /widget.js; equally consumable by agents.", "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Member slug, URL, or hostname. Optional; without it the ring is entered at its edges." }, { "$ref": "#/components/parameters/ApiVersion" } ], "responses": { "200": { "description": "Widget payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Widget" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/leaderboard": { "get": { "operationId": "getLeaderboard", "summary": "Members ranked by cumulative verified bids (paginated)", "description": "Auction rules: totals are cumulative across all bidders; higher total ranks higher; earlier join wins ties. to_take_first_usd is the single bid that takes #1, and #1 holds the homepage spot.", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "1-based alternative to offset; offset wins when both are present." }, { "$ref": "#/components/parameters/ApiVersion" } ], "responses": { "200": { "description": "A page of ranked members.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Leaderboard" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/register": { "post": { "operationId": "registerMember", "summary": "Join the ring ($1.00, paid over MPP; optional opening bid in the same payment)", "description": "Validation happens before the 402 challenge is issued, so a challenge means the registration will be accepted once paid. The URL must have an is-agentic.com report scoring at least 40. Include the optional bid field to join and place an opening leaderboard bid in one MPP payment (the challenge amount is fee + bid).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterRequest" } } } }, "responses": { "201": { "description": "Joined. Payment-Receipt header carries the receipt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterResponse" } } } }, "402": { "description": "Payment required (MPP). The WWW-Authenticate: Payment header carries the challenge. Pay it, then retry the identical request with the resulting Authorization credential. Successful paid responses include a Payment-Receipt header. A 402 means validation passed; it is safe to pay.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "URL already registered, or payment credential already used.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid fields, or is-agentic.com score below the minimum.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Validation or payment infrastructure temporarily unavailable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ] } }, "/api/bid": { "post": { "operationId": "placeBid", "summary": "Bid to rank a member higher (min $1.00, paid over MPP)", "description": "Anyone can fund any member. The paid amount adds to the member cumulative total, which sets leaderboard rank. There is no bid increment: any amount at or above the minimum is valid.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BidRequest" } } } }, "responses": { "200": { "description": "Bid applied; includes new total and rank.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BidResponse" } } } }, "402": { "description": "Payment required (MPP). The WWW-Authenticate: Payment header carries the challenge. Pay it, then retry the identical request with the resulting Authorization credential. Successful paid responses include a Payment-Receipt header. A 402 means validation passed; it is safe to pay.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Unknown member.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid or too-low amount.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ] } }, "/next": { "get": { "operationId": "redirectNext", "summary": "Embeddable redirect to the next member site", "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Member slug, member URL, or bare hostname to traverse from. Omitted: enters the ring at its edge." }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "agent", "mcp", "website" ] } }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ApiVersion" } ], "responses": { "302": { "description": "Redirect to the member site." }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/prev": { "get": { "operationId": "redirectPrev", "summary": "Embeddable redirect to the previous member site", "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Member slug, member URL, or bare hostname to traverse from. Omitted: enters the ring at its edge." }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "agent", "mcp", "website" ] } }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ApiVersion" } ], "responses": { "302": { "description": "Redirect to the member site." }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/random": { "get": { "operationId": "redirectRandom", "summary": "Embeddable redirect to a random member site", "responses": { "302": { "description": "Redirect to the member site." }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ] } } }, "components": { "schemas": { "Problem": { "type": "object", "description": "RFC 9457 problem details, extended with a machine-readable code.", "required": [ "title", "status", "detail", "code" ], "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable error code, e.g. invalid_url, already_registered, agentic_score_too_low, bid_too_low, unknown_member, credential_reused, payments_unconfigured." } }, "additionalProperties": true }, "Member": { "type": "object", "required": [ "slug", "name", "url", "kind", "category", "ring_position", "joined_at", "bid_total_usd", "links" ], "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "kind": { "type": "string", "enum": [ "agent", "mcp", "website" ] }, "category": { "type": "string" }, "description": { "type": "string" }, "agentic_score": { "type": [ "integer", "null" ], "description": "is-agentic.com score at registration time (0-100)." }, "agentic_report": { "type": [ "string", "null" ], "format": "uri" }, "ring_position": { "type": "integer" }, "joined_at": { "type": "string", "format": "date-time" }, "bid_total_usd": { "type": "string", "description": "Cumulative verified bids, USD with two decimals." }, "links": { "type": "object", "properties": { "self": { "type": "string", "format": "uri" }, "next": { "type": "string", "format": "uri" }, "prev": { "type": "string", "format": "uri" }, "site": { "type": "string", "format": "uri" } } } } }, "PageMeta": { "type": "object", "description": "Pagination envelope fields shared by list endpoints.", "properties": { "total": { "type": "integer", "description": "Total items across all pages." }, "count": { "type": "integer", "description": "Items in this page." }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "links": { "type": "object", "properties": { "next": { "type": [ "string", "null" ], "format": "uri" }, "prev": { "type": [ "string", "null" ], "format": "uri" } } } } }, "MemberList": { "allOf": [ { "$ref": "#/components/schemas/PageMeta" }, { "type": "object", "required": [ "members" ], "properties": { "members": { "type": "array", "items": { "$ref": "#/components/schemas/Member" } } } } ] }, "Traversal": { "type": "object", "required": [ "direction", "member" ], "properties": { "direction": { "type": "string", "enum": [ "next", "prev", "random" ] }, "member": { "$ref": "#/components/schemas/Member" } } }, "MemberDetail": { "type": "object", "required": [ "member" ], "properties": { "member": { "allOf": [ { "$ref": "#/components/schemas/Member" }, { "type": "object", "properties": { "leaderboard_rank": { "type": [ "integer", "null" ] } } } ] } } }, "CategoryList": { "type": "object", "required": [ "count", "categories" ], "properties": { "count": { "type": "integer" }, "categories": { "type": "array", "items": { "type": "object", "required": [ "category", "members" ], "properties": { "category": { "type": "string" }, "members": { "type": "integer" }, "links": { "type": "object", "properties": { "members": { "type": "string", "format": "uri" } } } } } } } }, "Leaderboard": { "allOf": [ { "$ref": "#/components/schemas/PageMeta" }, { "$ref": "#/components/schemas/LeaderboardBody" } ] }, "LeaderboardBody": { "type": "object", "required": [ "leaderboard" ], "properties": { "rules": { "type": "object", "properties": { "minimum_bid_usd": { "type": "string" }, "ranking": { "type": "string" }, "bid": { "type": "string" } } }, "leaderboard": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/Member" }, { "type": "object", "required": [ "rank" ], "properties": { "rank": { "type": "integer" }, "to_take_first_usd": { "type": [ "string", "null" ], "description": "The single bid that would put this member at #1. Null for the current leader." } } } ] } } } }, "RegisterRequest": { "type": "object", "required": [ "name", "url", "kind" ], "properties": { "name": { "type": "string", "maxLength": 80 }, "url": { "type": "string", "format": "uri", "maxLength": 300 }, "kind": { "type": "string", "enum": [ "agent", "mcp", "website" ] }, "category": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,31}$", "default": "general" }, "description": { "type": "string", "maxLength": 300 }, "bid": { "type": "string", "description": "Optional opening leaderboard bid in USD (minimum applies). Fee and bid settle as one MPP payment — no second transaction needed. Omit to register without bidding." } } }, "RegisterResponse": { "type": "object", "required": [ "joined", "member" ], "properties": { "joined": { "type": "boolean" }, "member": { "$ref": "#/components/schemas/Member" }, "leaderboard_rank": { "type": [ "integer", "null" ], "description": "Present when an opening bid was included." }, "to_take_first_usd": { "type": [ "string", "null" ] }, "welcome": { "type": "string" } } }, "BidRequest": { "type": "object", "required": [ "member", "amount" ], "properties": { "member": { "type": "string", "description": "Member slug or URL." }, "amount": { "type": "string", "description": "USD, two decimals max, at or above the minimum. No increments." } } }, "Widget": { "type": "object", "required": [ "ring", "links" ], "properties": { "ring": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "count": { "type": "integer" } } }, "member": { "oneOf": [ { "$ref": "#/components/schemas/Member" }, { "type": "null" } ] }, "prev": { "oneOf": [ { "$ref": "#/components/schemas/Member" }, { "type": "null" } ] }, "next": { "oneOf": [ { "$ref": "#/components/schemas/Member" }, { "type": "null" } ] }, "links": { "type": "object", "additionalProperties": { "type": "string", "format": "uri" } } } }, "BidResponse": { "type": "object", "required": [ "bid", "bid_total_usd" ], "properties": { "bid": { "type": "object", "properties": { "member": { "type": "string" }, "amount_usd": { "type": "string" } } }, "bid_total_usd": { "type": "string" }, "leaderboard_rank": { "type": [ "integer", "null" ] }, "to_take_first_usd": { "type": [ "string", "null" ] }, "links": { "type": "object", "additionalProperties": { "type": "string", "format": "uri" } } } } }, "parameters": { "ApiVersion": { "name": "Api-Version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ] }, "description": "API version selector. Optional; the current and only version is 1, echoed on every response." } }, "responses": { "RateLimited": { "description": "Rate limit exceeded (120/min per client). Retry-After indicates when to retry.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }