{ "openapi": "3.2.0", "info": { "title": "web.23signs.org", "version": "0.1.0", "summary": "Web pages as clean markdown, JSON or HTML; search over papers, news and Wikipedia; change notifications in-band with HTTP Events Query.", "description": "A stateless service for agents. Every request is processed on demand and nothing is stored beyond a one-day edge cache.\nNo authentication, no API keys; free while in beta, 60 requests a minute per address. A paid tier over x402 after a daily\nfree allowance is planned; prices will appear in `GET /v1/status` and here before anything is charged.\n\nThis document is OpenAPI 3.2 because the watch operations use the HTTP QUERY method (RFC 10008), which 3.2 can describe\nas a `query` operation. The subscription semantics follow draft-gupta-httpapi-events-query: `QUERY` the resource with\n`Content-Type: application/events+json` and an `Events: duration=N` header; the response stays open and carries\nnotifications in-band over the carrier negotiated with `Accept` (multipart/mixed, application/json-seq,\napplication/x-ndjson, text/event-stream). Resources that accept a subscription advertise `Accept-Query: application/events+json`.\n\nEvery JSON body carries a `_links` object (self, fetch, page, watch, search, status, openapi, catalog, describedby) and\nevery response carries a `Link` header with rel=\"service-desc\" to the RFC 9727 catalog and this document. Errors are\nRFC 9457 application/problem+json with `type` `https://web.23signs.org/errors/`.\n\nBuilt on web2md. Content belongs to the sites it comes from.\n", "contact": { "name": "23signs", "url": "https://23signs.org" }, "license": { "name": "Service terms", "url": "https://web.23signs.org/README.md" } }, "externalDocs": { "description": "Agent skill file", "url": "https://web.23signs.org/SKILL.md" }, "servers": [ { "url": "https://web.23signs.org" } ], "x-service-info": { "name": "web.23signs.org", "catalog": "https://web.23signs.org/.well-known/api-catalog", "mcp": "https://web.23signs.org/mcp", "llms": "https://web.23signs.org/llms.txt", "skill": "https://web.23signs.org/SKILL.md", "pricing": "free while in beta" }, "tags": [ { "name": "fetch", "description": "Pages as clean content" }, { "name": "search", "description": "Papers, news, Wikipedia" }, { "name": "watch", "description": "Events Query subscriptions" }, { "name": "status" } ], "paths": { "/v1/fetch": { "post": { "tags": [ "fetch" ], "operationId": "fetchPages", "summary": "Fetch up to 10 URLs as markdown, JSON blocks or clean HTML", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FetchRequest" }, "example": { "urls": [ "https://example.com/", "https://arxiv.org/abs/1706.03762" ], "format": "markdown", "links": true } } } }, "responses": { "200": { "description": "Results and per-URL errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FetchResponse" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "422": { "description": "Invalid CSS selector", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "$ref": "#/components/responses/Problem" } } }, "query": { "tags": [ "watch" ], "operationId": "watchPage", "summary": "Events Query subscription to a page", "description": "Hold the connection open for `Events: duration=N` seconds (up to 3600) and receive a notification each time the\nextracted content of `url` changes. With `events` in the body the response is a stream over the negotiated carrier:\nthe current content first when `state` is true, then `change` notifications with the lines added and removed, a\n`heartbeat` every 50 s while idle, and `end` when the duration or the check budget (40 checks) runs out. Without\n`events` the request long-polls and returns one JSON notification: the first `change`, or `timeout`.\nNothing is stored; disconnecting ends the watch. The interval is at least 15 s and is raised so the checks fit the budget.\n", "parameters": [ { "$ref": "#/components/parameters/Events" }, { "name": "Accept", "in": "header", "schema": { "type": "string", "enum": [ "multipart/mixed", "application/json-seq", "application/x-ndjson", "text/event-stream", "application/json" ] }, "description": "Stream carrier (with `events`), or notification type (without)" } ], "requestBody": { "required": true, "content": { "application/events+json": { "schema": { "$ref": "#/components/schemas/WatchRequest" }, "example": { "url": "https://example.com/pricing", "events": {}, "state": true, "interval": 60, "include_selectors": [ "#plans" ] } } } }, "responses": { "200": { "description": "Notification stream (with `events`) or a single notification (without)", "headers": { "Events": { "schema": { "type": "string" }, "description": "Effective `duration=N, interval=M`" }, "Incremental": { "schema": { "type": "string" }, "description": "`?1`: the body is delivered incrementally" }, "Accept-Query": { "schema": { "type": "string" } } }, "content": { "application/x-ndjson": { "schema": { "$ref": "#/components/schemas/Notification" } }, "application/json-seq": { "schema": { "$ref": "#/components/schemas/Notification" } }, "multipart/mixed": { "schema": { "$ref": "#/components/schemas/Notification" } }, "text/event-stream": { "schema": { "$ref": "#/components/schemas/Notification" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Notification" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "406": { "$ref": "#/components/responses/Problem" }, "415": { "description": "Missing Content-Type application/events+json, or no acceptable carrier", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "$ref": "#/components/responses/Problem" }, "502": { "$ref": "#/components/responses/Problem" } } } }, "/{url}": { "get": { "tags": [ "fetch" ], "operationId": "getPage", "summary": "One page as a markdown document", "description": "The target URL is the path, including its scheme: `GET /https://example.com/page`. Returns `text/markdown`\n(`# Title`, `**Source:** url`, `---`, body) or, with `Accept: application/json`, the result object. Options are\n`w2m.`-prefixed query parameters so the target's own query string passes through untouched.\n", "parameters": [ { "name": "url", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Absolute http or https URL, unencoded" }, { "name": "w2m.format", "in": "query", "schema": { "type": "string", "enum": [ "markdown", "json", "html" ] } }, { "name": "w2m.links", "in": "query", "schema": { "type": "string", "enum": [ "1", "true" ] } }, { "name": "w2m.select", "in": "query", "schema": { "type": "string" }, "description": "CSS include selectors, `||`-separated" }, { "name": "w2m.exclude", "in": "query", "schema": { "type": "string" }, "description": "CSS exclude selectors, `||`-separated" }, { "name": "w2m.ttl", "in": "query", "schema": { "type": "integer", "minimum": 0 } }, { "name": "w2m.render", "in": "query", "schema": { "type": "string", "enum": [ "auto", "never", "always" ] } } ], "responses": { "200": { "description": "The page", "headers": { "x-markdown-tokens": { "schema": { "type": "integer" }, "description": "Rough token estimate of the body" } }, "content": { "text/markdown": { "schema": { "type": "string" } }, "application/json": { "schema": { "$ref": "#/components/schemas/FetchResult" } }, "text/html": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" }, "502": { "$ref": "#/components/responses/Problem" } } }, "query": { "tags": [ "watch" ], "operationId": "watchPagePath", "summary": "Events Query subscription, page as path", "description": "Same as `QUERY /v1/fetch`; the body's `url` is taken from the path.", "parameters": [ { "name": "url", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Events" } ], "requestBody": { "content": { "application/events+json": { "schema": { "$ref": "#/components/schemas/WatchOptions" } } } }, "responses": { "200": { "description": "Notification stream or single notification", "content": { "application/x-ndjson": { "schema": { "$ref": "#/components/schemas/Notification" } } } } } } }, "/v1/search": { "get": { "tags": [ "search" ], "operationId": "search", "summary": "Search papers, news or Wikipedia", "parameters": [ { "name": "query", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "domain_type", "in": "query", "schema": { "type": "string", "enum": [ "research_paper", "news", "wikipedia", "web" ], "default": "web" }, "description": "web answers 501 until a backend is configured; see /v1/status" }, { "name": "include_domains", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated host names to keep" }, { "name": "exclude_domains", "in": "query", "schema": { "type": "string" } }, { "name": "language", "in": "query", "schema": { "type": "string" }, "description": "Two-letter code; news language, Wikipedia edition" }, { "name": "location", "in": "query", "schema": { "type": "string" } }, { "name": "recency_minutes", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 5256000 }, "description": "News only; cannot combine with the dates" }, { "name": "after_date", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "before_date", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "pub_year_min", "in": "query", "schema": { "type": "integer" }, "description": "research_paper only" }, { "name": "pub_year_max", "in": "query", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 10, "default": 0 } } ], "responses": { "200": { "description": "Ranked results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "501": { "description": "WEB_SEARCH_UNCONFIGURED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "UPSTREAM_RATE_LIMITED (GDELT throttles shared addresses; retry)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "query": { "tags": [ "watch" ], "operationId": "watchSearch", "summary": "Events Query subscription to a search", "description": "Repeats the search every `interval` seconds (at least 60) and reports `new_results` that were not in earlier result sets.", "parameters": [ { "$ref": "#/components/parameters/Events" } ], "requestBody": { "required": true, "content": { "application/events+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SearchParams" }, { "type": "object", "properties": { "events": { "type": "object" }, "state": { "type": "boolean" }, "interval": { "type": "integer", "minimum": 60 } } } ] } } } }, "responses": { "200": { "description": "Notification stream", "content": { "application/x-ndjson": { "schema": { "$ref": "#/components/schemas/Notification" } } } } } } }, "/v1/status": { "get": { "tags": [ "status" ], "operationId": "getStatus", "summary": "Limits, live search backends, pricing", "responses": { "200": { "description": "Status document", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } } } } }, "components": { "parameters": { "Events": { "name": "Events", "in": "header", "schema": { "type": "string", "pattern": "^duration=\\d+" }, "description": "`duration=N` seconds, up to 3600 (default 300)" } }, "responses": { "Problem": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "schemas": { "Links": { "type": "object", "additionalProperties": { "type": "object", "properties": { "href": { "type": "string" }, "method": { "type": "string" }, "templated": { "type": "boolean" }, "type": { "type": "string" }, "title": { "type": "string" } } } }, "Problem": { "type": "object", "required": [ "type", "title", "status", "detail" ], "properties": { "type": { "type": "string", "format": "uri", "description": "`https://web.23signs.org/errors/`" }, "title": { "type": "string", "description": "The code, for example INVALID_URL, BLOCKED_URL, SELECTOR_NOT_MATCHED, RATE_LIMITED, UNSUPPORTED_MEDIA_TYPE, WEB_SEARCH_UNCONFIGURED" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "unmatched_selectors": { "type": "array", "items": { "type": "string" } }, "_links": { "$ref": "#/components/schemas/Links" } } }, "Selectors": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "FetchOptions": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "markdown", "json", "html" ], "default": "markdown" }, "links": { "type": "boolean", "default": false }, "image_links": { "type": "boolean", "default": false }, "iframe_links": { "type": "boolean", "default": false }, "include_selectors": { "$ref": "#/components/schemas/Selectors" }, "exclude_selectors": { "$ref": "#/components/schemas/Selectors" }, "ttl": { "type": "integer", "minimum": 0, "description": "Omit to accept any cached copy (up to a day); 0 for a live fetch; N for copies younger than N seconds" }, "per_url_timeout_ms": { "type": "integer", "minimum": 1, "maximum": 110000 }, "if_none_match": { "type": "string", "description": "Single URL only" }, "if_modified_since": { "type": "string", "description": "Single URL only" }, "include_etag_and_last_modified": { "type": "boolean", "default": false }, "render": { "type": "string", "enum": [ "auto", "never", "always" ], "default": "auto", "description": "Headless browser for JavaScript-rendered pages" } } }, "FetchRequest": { "allOf": [ { "type": "object", "required": [ "urls" ], "properties": { "urls": { "type": "array", "minItems": 1, "maxItems": 10, "items": { "type": "string", "format": "uri" } } } }, { "$ref": "#/components/schemas/FetchOptions" } ] }, "Block": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "heading", "paragraph", "quote", "list", "table", "code", "image", "hidden" ] }, "level": { "type": "integer" }, "text": { "type": "string" }, "ordered": { "type": "boolean" }, "items": { "type": "array", "items": { "type": "string" } }, "rows": { "type": "array", "items": { "type": "array", "items": { "type": "string" } } }, "language": { "type": [ "string", "null" ] }, "alt": { "type": "string" }, "src": { "type": "string" }, "reason": { "type": "string" } } }, "FetchResult": { "type": "object", "required": [ "url", "final_url", "format", "source", "latency_ms" ], "properties": { "url": { "type": "string" }, "final_url": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "language": { "type": [ "string", "null" ] }, "author": { "type": [ "string", "null" ] }, "published_date": { "type": [ "string", "null" ] }, "format": { "type": "string", "enum": [ "markdown", "json", "html" ] }, "text": { "oneOf": [ { "type": "string" }, { "type": "object", "properties": { "blocks": { "type": "array", "items": { "$ref": "#/components/schemas/Block" } } } }, { "type": "null" } ], "description": "Markdown or HTML string, the block tree for json, null on a 304" }, "links": { "type": "array", "items": { "type": "string" } }, "image_links": { "type": "array", "items": { "type": "string" } }, "iframe_links": { "type": "array", "items": { "type": "string" } }, "not_modified": { "type": "boolean" }, "etag": { "type": "string" }, "last_modified": { "type": "string" }, "unmatched_selectors": { "type": "array", "items": { "type": "string" } }, "source": { "type": "string", "enum": [ "static", "browser", "document", "text" ] }, "latency_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "age_seconds": { "type": "integer" }, "_links": { "$ref": "#/components/schemas/Links" } } }, "FetchError": { "type": "object", "required": [ "url", "error", "message" ], "properties": { "url": { "type": "string" }, "error": { "type": "string", "description": "Same codes as the problem types" }, "message": { "type": "string" }, "status": { "type": "integer", "description": "The origin's HTTP status, for HTTP_ERROR" }, "unmatched_selectors": { "type": "array", "items": { "type": "string" } } } }, "FetchResponse": { "type": "object", "required": [ "results", "errors" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/FetchResult" } }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/FetchError" } }, "_links": { "$ref": "#/components/schemas/Links" } } }, "WatchOptions": { "allOf": [ { "$ref": "#/components/schemas/FetchOptions" }, { "type": "object", "properties": { "events": { "type": "object", "description": "Present for a stream; `accept` picks the notification schema", "properties": { "accept": { "type": "string", "enum": [ "application/json", "application/ld+json", "application/activity+json" ] } } }, "state": { "type": "boolean", "description": "Send the current content first" }, "interval": { "type": "integer", "minimum": 15, "description": "Seconds between checks" }, "include_text": { "type": "boolean", "description": "Include the new text on every change" } } } ] }, "WatchRequest": { "allOf": [ { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri" } } }, { "$ref": "#/components/schemas/WatchOptions" } ] }, "Notification": { "type": "object", "required": [ "type", "resource", "at" ], "properties": { "type": { "type": "string", "enum": [ "state", "change", "heartbeat", "error", "end", "timeout" ] }, "resource": { "type": "string" }, "at": { "type": "string", "format": "date-time" }, "fingerprint": { "type": "string" }, "previous_fingerprint": { "type": "string" }, "state": { "description": "The current content (markdown document or result object), on `state`" }, "title": { "type": [ "string", "null" ] }, "delta": { "type": "object", "properties": { "added": { "type": "array", "items": { "type": "string" } }, "removed": { "type": "array", "items": { "type": "string" } }, "added_count": { "type": "integer" }, "removed_count": { "type": "integer" } } }, "text": { "type": "string" }, "new_results": { "type": "array", "items": { "$ref": "#/components/schemas/SearchResult" } }, "code": { "type": "string" }, "message": { "type": "string" }, "checks": { "type": "integer" }, "changed": { "type": "boolean" } } }, "SearchParams": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string" }, "domain_type": { "type": "string", "enum": [ "research_paper", "news", "wikipedia", "web" ] }, "include_domains": { "type": "string" }, "exclude_domains": { "type": "string" }, "language": { "type": "string" }, "location": { "type": "string" }, "recency_minutes": { "type": "integer" }, "after_date": { "type": "string" }, "before_date": { "type": "string" }, "pub_year_min": { "type": "integer" }, "pub_year_max": { "type": "integer" }, "page": { "type": "integer" } } }, "SearchResult": { "type": "object", "required": [ "position", "site_name", "title", "url" ], "properties": { "position": { "type": "integer" }, "site_name": { "type": "string" }, "title": { "type": "string" }, "snippet": { "type": "string" }, "url": { "type": "string" }, "date": { "type": "string" }, "publisher": { "type": "string" }, "language": { "type": "string" }, "authors": { "type": "array", "items": { "type": "string" } }, "venue": { "type": "string" }, "year": { "type": "integer" }, "cited_by_count": { "type": "integer" }, "pdf_url": { "type": "string" } } }, "SearchResponse": { "type": "object", "required": [ "query", "domain_type", "results", "total_results", "page" ], "properties": { "query": { "type": "string" }, "domain_type": { "type": "string" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/SearchResult" } }, "total_results": { "type": "integer" }, "page": { "type": "integer" }, "_links": { "$ref": "#/components/schemas/Links" } } }, "Status": { "type": "object", "properties": { "service": { "type": "string" }, "version": { "type": "string" }, "pricing": { "type": "object", "properties": { "model": { "type": "string" }, "configured": { "type": "boolean" }, "note": { "type": "string" } } }, "limits": { "type": "object", "properties": { "requestsPerMinute": { "type": "integer" }, "maxUrlsPerFetch": { "type": "integer" }, "maxBodyBytes": { "type": "integer" }, "watch": { "type": "object", "properties": { "maxSeconds": { "type": "integer" }, "maxChecks": { "type": "integer" }, "minIntervalSeconds": { "type": "object", "properties": { "fetch": { "type": "integer" }, "search": { "type": "integer" } } }, "carriers": { "type": "array", "items": { "type": "string" } } } } } }, "search": { "type": "object", "properties": { "backends": { "type": "object", "additionalProperties": { "type": [ "array", "null" ], "items": { "type": "string" } } }, "note": { "type": [ "string", "null" ] } } }, "features": { "type": "object", "properties": { "browserRendering": { "type": "boolean" }, "documents": { "type": "boolean" }, "hiddenTextMarkers": { "type": "boolean" } } }, "_links": { "$ref": "#/components/schemas/Links" } } } } } }