{ "openapi": "3.1.0", "info": { "title": "OnlyDoge website API", "version": "1.0.0", "summary": "Public HTTP surface of www.onlydoge.io: agent discovery resources, Markdown documentation and the browser chat transport.", "description": "OnlyDoge by EasyDoge is a Dogecoin Mainnet explorer. This document describes the resources served by **www.onlydoge.io**. Structured Dogecoin records (blocks, transactions, addresses, mempool, analytics) are served by the separate, authenticated **OnlyDoge Platform API**, whose authoritative OpenAPI document is https://platform.onlydoge.io/openapi/json.\n\n## Errors\n\nEvery error from an `/api` path, every unsupported method, every unsupported representation and every unknown `/api` URL is an [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) problem document (`application/problem+json`). Problems carry the standard `type`, `title`, `status`, `detail` and `instance` members plus the extension members `code` (stable machine-readable identifier) and `hint` (resolution guidance). Each `type` URI dereferences to documentation at https://www.onlydoge.io/developers. Unknown paths outside `/api` return HTTP 404 with a Markdown body for non-browser clients.\n\n## Rate limiting\n\nChat responses carry the IETF `RateLimit` and `RateLimit-Policy` fields (draft-ietf-httpapi-ratelimit-headers; policy `\"chat\"`, 10 requests per 60 seconds per client), the earlier-draft `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` fields, and `Retry-After` on 429 responses.\n\n## Versioning and deprecation\n\nAPI paths are versioned in the URL (`/api/v1/`). Additive changes never change the version. Breaking changes ship under a new prefix while the previous version keeps working for at least 90 days and announces its status with the RFC 9745 `Deprecation` header, the RFC 8594 `Sunset` header and `Link` relations `deprecation`, `sunset` and `successor-version`. Policy: https://www.onlydoge.io/developers#versioning-and-deprecation. Current deprecation: `/api/chat` is an alias of `/api/v1/chat` with a sunset of 2027-01-01T00:00:00.000Z.\n\n## Content negotiation\n\nThe homepage and information pages serve HTML by default and Markdown when `text/markdown` outranks `text/html` in the Accept header; each also has a fixed `.md` URL. Interactive explorer pages are HTML only and answer 406 to other preferences. Agent guidance starts at https://www.onlydoge.io/llms.txt.", "contact": { "name": "EasyDoge", "url": "https://www.onlydoge.io/contact" } }, "externalDocs": { "description": "OnlyDoge developer resources", "url": "https://www.onlydoge.io/developers" }, "servers": [ { "url": "https://www.onlydoge.io", "description": "Production" } ], "tags": [ { "name": "Discovery", "description": "Machine-readable entry points: llms.txt, the sitemap and this document." }, { "name": "Documentation", "description": "Information pages negotiated as HTML or Markdown." }, { "name": "Chat", "description": "Dogecoin AI Chat transport used by the OnlyDoge browser client." } ], "paths": { "/llms.txt": { "get": { "tags": [ "Discovery" ], "operationId": "getLlmsTxt", "summary": "Agent guidance index (llms.txt)", "description": "llmstxt.org-formatted index: when to use OnlyDoge, developer resources, trust pages and optional machine-readable documents.", "responses": { "200": { "description": "The llms.txt document.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" } }, "content": { "text/plain": { "schema": { "type": "string", "description": "Markdown following the llms.txt format: H1, blockquote summary, H2 sections of `- [name](url): notes` lines." } } } } } } }, "/sitemap.xml": { "get": { "tags": [ "Discovery" ], "operationId": "getSitemap", "summary": "XML sitemap of canonical indexable pages", "responses": { "200": { "description": "Sitemaps XML protocol document.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" } }, "content": { "application/xml": { "schema": { "type": "string", "description": "urlset in the http://www.sitemaps.org/schemas/sitemap/0.9 namespace with loc and lastmod per URL." } } } } } } }, "/openapi.json": { "get": { "tags": [ "Discovery" ], "operationId": "getOpenApiDocument", "summary": "This OpenAPI document", "responses": { "200": { "description": "OpenAPI 3.1 document for the website API.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "Link": { "$ref": "#/components/headers/Link" } }, "content": { "application/json": { "schema": { "type": "object", "description": "OpenAPI 3.1 document.", "required": [ "openapi", "info", "paths" ], "properties": { "openapi": { "type": "string", "pattern": "^3\\.1\\." }, "info": { "type": "object" }, "paths": { "type": "object" }, "components": { "type": "object" } } } } } } } } }, "/": { "get": { "tags": [ "Documentation" ], "operationId": "getHomepage", "summary": "Homepage (HTML or Markdown overview)", "description": "The Markdown representation is a product overview with links to explorer views and information pages. It contains no live chain data.", "responses": { "200": { "description": "The page in the negotiated representation. Browsers receive HTML; clients that prefer text/markdown in the Accept header receive Markdown. The response varies on Accept and is marked no-store so caches cannot mix representations.", "headers": { "Vary": { "$ref": "#/components/headers/Vary" }, "Link": { "$ref": "#/components/headers/Link" }, "Cache-Control": { "$ref": "#/components/headers/Cache-Control" } }, "content": { "text/html": { "schema": { "type": "string", "description": "Server-rendered HTML page." } }, "text/markdown": { "schema": { "type": "string", "description": "GitHub-flavoured Markdown, UTF-8." } } } }, "406": { "$ref": "#/components/responses/NotAcceptable" } } } }, "/index.md": { "get": { "tags": [ "Documentation" ], "operationId": "getHomepageMarkdown", "summary": "Homepage overview as Markdown", "responses": { "200": { "description": "Markdown overview of OnlyDoge.", "headers": { "Vary": { "$ref": "#/components/headers/Vary" }, "Link": { "$ref": "#/components/headers/Link" }, "Cache-Control": { "$ref": "#/components/headers/Cache-Control" } }, "content": { "text/markdown": { "schema": { "type": "string", "description": "GitHub-flavoured Markdown, UTF-8." } } } } } } }, "/{page}": { "get": { "tags": [ "Documentation" ], "operationId": "getInformationPage", "summary": "Information page (HTML or Markdown)", "parameters": [ { "name": "page", "in": "path", "required": true, "description": "Information page name.", "schema": { "type": "string", "enum": [ "about", "contact", "privacy", "developers", "agent-instructions" ] } } ], "responses": { "200": { "description": "The page in the negotiated representation. Browsers receive HTML; clients that prefer text/markdown in the Accept header receive Markdown. The response varies on Accept and is marked no-store so caches cannot mix representations.", "headers": { "Vary": { "$ref": "#/components/headers/Vary" }, "Link": { "$ref": "#/components/headers/Link" }, "Cache-Control": { "$ref": "#/components/headers/Cache-Control" } }, "content": { "text/html": { "schema": { "type": "string", "description": "Server-rendered HTML page." } }, "text/markdown": { "schema": { "type": "string", "description": "GitHub-flavoured Markdown, UTF-8." } } } }, "406": { "$ref": "#/components/responses/NotAcceptable" } } } }, "/{page}.md": { "get": { "tags": [ "Documentation" ], "operationId": "getInformationPageMarkdown", "summary": "Information page as Markdown", "parameters": [ { "name": "page", "in": "path", "required": true, "description": "Information page name.", "schema": { "type": "string", "enum": [ "about", "contact", "privacy", "developers", "agent-instructions" ] } } ], "responses": { "200": { "description": "Markdown rendering of the information page.", "headers": { "Vary": { "$ref": "#/components/headers/Vary" }, "Link": { "$ref": "#/components/headers/Link" }, "Cache-Control": { "$ref": "#/components/headers/Cache-Control" } }, "content": { "text/markdown": { "schema": { "type": "string", "description": "GitHub-flavoured Markdown, UTF-8." } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/chat": { "post": { "tags": [ "Chat" ], "operationId": "postChat", "summary": "Stream a Dogecoin AI Chat answer (browser client)", "description": "Streams a Dogecoin AI Chat answer for the OnlyDoge web client. Requests must come from a verified browser session (Vercel BotID); automated clients receive a 403 problem. Each client may send 10 requests per 60 seconds; every response carries RateLimit headers and a 429 adds Retry-After. Other methods return 405 with an Allow header, and OPTIONS returns 204 with Allow: POST, OPTIONS. Programmatic Dogecoin data belongs to the OnlyDoge Platform API (https://platform.onlydoge.io/openapi).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatRequest" }, "example": { "messages": [ { "id": "m1", "role": "user", "parts": [ { "type": "text", "text": "What is in the latest Dogecoin block?" } ] } ], "timeZone": "Pacific/Auckland" } } } }, "responses": { "200": { "description": "AI SDK UI message stream: server-sent events carrying text deltas, tool traces, citations, entity cards and analytics results, ending with a finish part.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "text/event-stream": { "schema": { "type": "string", "description": "Server-sent events. Each `data:` line is a JSON-encoded AI SDK UI message stream part." } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "403": { "$ref": "#/components/responses/AccessDenied" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/ChatUnavailable" } } } }, "/api/chat": { "post": { "tags": [ "Chat" ], "operationId": "postChatLegacy", "deprecated": true, "summary": "Deprecated alias of POST /api/v1/chat", "description": "Identical to POST /api/v1/chat. Deprecated since 2026-09-07T00:00:00.000Z; sunset 2027-01-01T00:00:00.000Z. Every response carries Deprecation, Sunset and Link (rel deprecation, sunset, successor-version) headers.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatRequest" }, "example": { "messages": [ { "id": "m1", "role": "user", "parts": [ { "type": "text", "text": "What is in the latest Dogecoin block?" } ] } ], "timeZone": "Pacific/Auckland" } } } }, "responses": { "200": { "description": "AI SDK UI message stream: server-sent events carrying text deltas, tool traces, citations, entity cards and analytics results, ending with a finish part.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "Link": { "$ref": "#/components/headers/Link" } }, "content": { "text/event-stream": { "schema": { "type": "string", "description": "Server-sent events. Each `data:` line is a JSON-encoded AI SDK UI message stream part." } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "403": { "$ref": "#/components/responses/AccessDenied" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/ChatUnavailable" } } } } }, "components": { "schemas": { "Problem": { "type": "object", "properties": { "type": { "type": "string", "description": "URI identifying the problem type. Dereference it for human-readable documentation." }, "title": { "type": "string", "description": "Short, human-readable summary of the problem type." }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "HTTP status code generated by the origin server." }, "detail": { "type": "string", "description": "Human-readable explanation specific to this occurrence." }, "instance": { "description": "URI reference identifying the specific occurrence.", "type": "string" }, "code": { "type": "string", "enum": [ "not_found", "method_not_allowed", "not_acceptable", "invalid_request", "access_denied", "rate_limited", "chat_unavailable" ], "description": "Stable machine-readable error code. Branch on this field, not on the title." }, "hint": { "type": "string", "description": "Resolution guidance: what to change or where to look next." } }, "required": [ "type", "title", "status", "detail", "code", "hint" ], "additionalProperties": {}, "title": "Problem", "description": "RFC 9457 Problem Details with OnlyDoge extension members `code` and `hint`. Unknown members must be ignored.", "examples": [ { "type": "https://www.onlydoge.io/developers#problem-not_found", "title": "Not Found", "status": 404, "detail": "No API resource exists at /api/does-not-exist.", "instance": "/api/does-not-exist", "code": "not_found", "hint": "Check the URL against the sitemap at https://www.onlydoge.io/sitemap.xml, start from https://www.onlydoge.io/llms.txt for Markdown documentation, or read https://www.onlydoge.io/developers for the API surface. Explorer views use /blocks, /blocks/{height-or-hash}, /tx/{txid}, /address/{address} and /mempool." } ] }, "ChatRequest": { "type": "object", "properties": { "messages": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Client message id; the server generates one when missing.", "type": "string" }, "role": { "type": "string", "enum": [ "user", "assistant" ], "description": "Messages with any other role are dropped." }, "parts": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "text", "description": "Only text parts are read by the server." }, "text": { "type": "string", "minLength": 1, "description": "Message text." } }, "required": [ "type", "text" ], "additionalProperties": {} }, "description": "AI SDK UI message parts. Text parts are concatenated." } }, "required": [ "role", "parts" ], "additionalProperties": {} }, "description": "Conversation so far. The most recent 20 messages with text are sent to the model. Additional AI SDK transport fields (id, trigger, messageId, metadata, tools) are accepted and ignored." }, "timeZone": { "description": "IANA time zone used to resolve calendar words in analytics questions. Invalid or missing values fall back to the server default.", "type": "string" } }, "required": [ "messages" ], "additionalProperties": {}, "title": "ChatRequest", "description": "Request body accepted by the chat transport." } }, "responses": { "NotFound": { "description": "Not Found. No resource exists at the requested URL.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://www.onlydoge.io/developers#problem-not_found", "title": "Not Found", "status": 404, "detail": "No API resource exists at /api/does-not-exist.", "instance": "/api/does-not-exist", "code": "not_found", "hint": "Check the URL against the sitemap at https://www.onlydoge.io/sitemap.xml, start from https://www.onlydoge.io/llms.txt for Markdown documentation, or read https://www.onlydoge.io/developers for the API surface. Explorer views use /blocks, /blocks/{height-or-hash}, /tx/{txid}, /address/{address} and /mempool." } } } }, "MethodNotAllowed": { "description": "Method Not Allowed. The resource exists but does not support the request method.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Allow": { "$ref": "#/components/headers/Allow" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://www.onlydoge.io/developers#problem-method_not_allowed", "title": "Method Not Allowed", "status": 405, "detail": "GET is not supported for /api/v1/chat. Send POST with a JSON body, or OPTIONS to read the Allow header.", "instance": "/api/v1/chat", "code": "method_not_allowed", "hint": "Retry with one of the methods listed in the Allow response header." } } } }, "NotAcceptable": { "description": "Not Acceptable. None of the representations requested in the Accept header are available for this resource.", "headers": { "Vary": { "$ref": "#/components/headers/Vary" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://www.onlydoge.io/developers#problem-not_acceptable", "title": "Not Acceptable", "status": 406, "detail": "Supported representations for /blocks: text/html.", "instance": "/blocks", "code": "not_acceptable", "hint": "Interactive explorer pages are text/html only. The homepage and information pages also serve text/markdown; https://www.onlydoge.io/llms.txt lists every Markdown resource." } } } }, "InvalidRequest": { "description": "Invalid Request. The request body or parameters were not valid.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://www.onlydoge.io/developers#problem-invalid_request", "title": "Invalid Request", "status": 400, "detail": "Dogecoin AI Chat requires a message.", "instance": "/api/v1/chat", "code": "invalid_request", "hint": "Send a JSON body with a non-empty \"messages\" array whose entries have a \"role\" of \"user\" or \"assistant\" and text content, as described in the OpenAPI document at /openapi.json." } } } }, "AccessDenied": { "description": "Access Denied. The request was not accepted as a verified browser session.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://www.onlydoge.io/developers#problem-access_denied", "title": "Access Denied", "status": 403, "detail": "Dogecoin AI Chat access denied.", "instance": "/api/v1/chat", "code": "access_denied", "hint": "The chat transport serves the OnlyDoge browser client and is protected by bot verification. Programmatic access to Dogecoin records uses the OnlyDoge Platform API with a provisioned token; see https://www.onlydoge.io/developers." } } } }, "RateLimited": { "description": "Too Many Requests. The request quota for this resource has been used.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://www.onlydoge.io/developers#problem-rate_limited", "title": "Too Many Requests", "status": 429, "detail": "Dogecoin AI Chat rate limit exceeded.", "instance": "/api/v1/chat", "code": "rate_limited", "hint": "Wait for the number of seconds given in the Retry-After header before retrying. The RateLimit and RateLimit-Policy headers describe the remaining quota and the policy window." } } } }, "ChatUnavailable": { "description": "Chat Unavailable. Dogecoin AI Chat cannot answer right now.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://www.onlydoge.io/developers#problem-chat_unavailable", "title": "Chat Unavailable", "status": 503, "detail": "Dogecoin AI Chat unavailable: The Dogecoin AI Chat is unavailable right now.", "instance": "/api/v1/chat", "code": "chat_unavailable", "hint": "Retry later. Explorer pages, Markdown documentation and the OnlyDoge Platform API stay available while chat is unavailable." } } } } }, "headers": { "RateLimit": { "description": "Current service limit for the \"chat\" policy (draft-ietf-httpapi-ratelimit-headers): r is the remaining quota, t the seconds until the window resets.", "schema": { "type": "string" }, "example": "\"chat\";r=9;t=60" }, "RateLimit-Policy": { "description": "Quota policy: q requests per w seconds.", "schema": { "type": "string" }, "example": "\"chat\";q=10;w=60" }, "RateLimit-Limit": { "description": "Requests permitted per window (earlier-draft form of RateLimit-Policy q).", "schema": { "type": "string" }, "example": "10" }, "RateLimit-Remaining": { "description": "Requests remaining in the current window (earlier-draft form of RateLimit r).", "schema": { "type": "string" }, "example": "9" }, "RateLimit-Reset": { "description": "Seconds until the current window resets (earlier-draft form of RateLimit t).", "schema": { "type": "string" }, "example": "60" }, "Retry-After": { "description": "Seconds to wait before retrying a rate-limited request (RFC 9110).", "schema": { "type": "string" }, "example": "42" }, "Deprecation": { "description": "RFC 9745 Structured Field Date marking when the resource was deprecated.", "schema": { "type": "string" }, "example": "@1788739200" }, "Sunset": { "description": "RFC 8594 HTTP-date after which the resource may stop responding.", "schema": { "type": "string" }, "example": "Fri, 01 Jan 2027 00:00:00 GMT" }, "Link": { "description": "RFC 8288 web links. Deprecated resources link rel=deprecation, rel=sunset and rel=successor-version; documentation pages link rel=alternate (Markdown), rel=describedby (llms.txt) and rel=service-desc (this document).", "schema": { "type": "string" }, "example": "; rel=\"deprecation\"; type=\"text/html\", ; rel=\"sunset\"; type=\"text/html\", ; rel=\"successor-version\"" }, "Allow": { "description": "Methods supported by the resource (RFC 9110).", "schema": { "type": "string" }, "example": "POST, OPTIONS" }, "Vary": { "description": "Request headers that select the representation.", "schema": { "type": "string" }, "example": "Accept, Accept-Encoding" }, "Cache-Control": { "description": "Caching directives. Negotiated pages are no-store so caches cannot mix representations; discovery files are cacheable for five minutes.", "schema": { "type": "string" }, "example": "no-store" } } }, "x-versioning-policy": { "scheme": "url-path", "currentVersion": "v1", "deprecationNoticeDays": 90, "deprecationHeaders": [ "Deprecation", "Sunset", "Link" ], "policyUrl": "https://www.onlydoge.io/developers#versioning-and-deprecation", "deprecations": [ { "path": "/api/chat", "successor": "/api/v1/chat", "deprecatedAt": "2026-09-07T00:00:00.000Z", "sunsetAt": "2027-01-01T00:00:00.000Z" } ] }, "x-rate-limit-policy": { "policy": "chat", "quota": 10, "windowSeconds": 60, "partition": "client IP", "headers": [ "RateLimit", "RateLimit-Policy", "RateLimit-Limit", "RateLimit-Remaining", "RateLimit-Reset", "Retry-After" ], "appliesTo": [ "/api/v1/chat", "/api/chat" ] }, "x-website-spec-url": "https://www.onlydoge.io/openapi.json" }