{"openapi":"3.1.1","info":{"title":"Craig Coffee reading and subscription interface","version":"2026-10-01.1","description":"Official public website, book and article sources, with bounded Daily Cup requests. This schema describes this site; it is not a universal agent-discovery registry."},"servers":[{"url":"https://usedtostutter.com"}],"paths":{"/site.xml":{"get":{"operationId":"readPublicWebsiteXml","summary":"Read the public website page text and reading links in XML.","description":"Includes website facts and policies, with links to the separate complete-book files. Check the final end_of_document marker and page counts for complete snapshot retrieval.","responses":{"200":{"description":"Public website snapshot.","content":{"application/xml":{"schema":{"type":"string"}}}}}}},"/site.txt":{"get":{"operationId":"readPublicWebsiteText","summary":"Read the complete public website or one numbered website page as plain text.","description":"Contains the same visible public page text as site XML. The complete book is separate. Follow next_website_page and keep its snapshot identifier when reading page by page. Verify scope, counts and final END_OF_DOCUMENT. HTTP 409 means the snapshot changed and reading must restart.","parameters":[{"in":"query","name":"page","schema":{"type":"integer","minimum":1},"description":"Omit for the complete website; use 1 to begin page-by-page reading. These are website pages, not original book pages."},{"in":"query","name":"snapshot","schema":{"type":"string","pattern":"^[a-f0-9]{64}$"},"description":"Use the identifier supplied by the preceding response to avoid mixing snapshots."}],"responses":{"200":{"description":"Complete selected public website text.","content":{"text/plain":{"schema":{"type":"string"}}}},"400":{"description":"Invalid or repeated page/snapshot parameter."},"409":{"description":"Snapshot changed; restart at /site.txt?page=1.","content":{"text/plain":{"schema":{"type":"string"}}}}}}},"/reader/catalog.json":{"get":{"operationId":"getPublishedArticleCatalog","summary":"Get article identifiers, original URLs, XML and JSON reading URLs, and passage citations.","responses":{"200":{"description":"Published article catalog. Use its returned identifiers and reading URLs.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/for-ai/subscription-offer.json":{"get":{"operationId":"getDailyCupOffer","summary":"Read current subscription conditions and interface availability.","responses":{"200":{"description":"Current offer.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/for-ai/capabilities.json":{"get":{"operationId":"getCraigCoffeeCapabilities","summary":"Read currently available reading and subscription paths.","responses":{"200":{"description":"Capabilities.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/reader/book/manifest.json":{"get":{"operationId":"getCompleteBookManifest","summary":"Get all original pages, chapters, formats, edition and integrity references.","responses":{"200":{"description":"Complete book manifest.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/reader/search":{"get":{"operationId":"searchCraigCoffeeSources","summary":"Find original passages in the book and published articles.","description":"Lexical search of book and article sources. For website facts and policies, use /site.xml or /for-ai/capabilities.json; for current subscription availability, use /for-ai/subscription-offer.json. Open a returned read_url before summarizing or citing.","parameters":[{"in":"query","name":"q","required":true,"schema":{"type":"string","minLength":1,"maxLength":240}},{"in":"query","name":"scope","schema":{"type":"string","enum":["all","articles","book"],"default":"all"}},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":20,"default":8}}],"responses":{"200":{"description":"Sources with original context and citations.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid search parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/reader/articles/{article_id}.{format}":{"get":{"operationId":"readPublishedArticle","summary":"Read one complete published article.","description":"Use a returned catalog or search identifier. The top-level source_markdown is the whole article; sections repeat passages for citation. Cite canonical_url for the article or citation_url for a passage.","parameters":[{"in":"path","name":"article_id","required":true,"schema":{"type":"string","pattern":"^CC-[0-9]+$"},"description":"Use an id returned by /reader/catalog.json or source search."},{"in":"path","name":"format","required":true,"schema":{"type":"string","enum":["xml","json"]},"description":"Choose XML or JSON for the same authored source."}],"responses":{"200":{"description":"Complete selected source, with author and original citation metadata.","content":{"application/xml":{"schema":{"type":"string"}},"application/json":{"schema":{"type":"object"}}}},"404":{"description":"No public source exists at this address. Use a URL returned by the catalog or manifest.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/reader/book/chapters/{section_id}.{format}":{"get":{"operationId":"readCurrentBookSection","summary":"Read one section of the current book edition.","description":"Public reading requires no account. Use exact returned URLs and keep one edition throughout a reading. A page or section is not the whole book; check scope, page and block counts, and end_of_document. Cite the supplied original-page citation_url.","parameters":[{"in":"path","name":"section_id","required":true,"schema":{"type":"string","pattern":"^[a-z0-9-]+$"},"description":"Use a sections[].id returned by the selected book manifest."},{"in":"path","name":"format","required":true,"schema":{"type":"string","enum":["xml","json"]},"description":"Choose XML or JSON for the same authored source."}],"responses":{"200":{"description":"Complete selected source, with author and original citation metadata.","content":{"application/xml":{"schema":{"type":"string"}},"application/json":{"schema":{"type":"object"}}}},"404":{"description":"No public source exists at this address. Use a URL returned by the catalog or manifest.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/reader/book/pages/{page_number}.{format}":{"get":{"operationId":"readCurrentBookPage","summary":"Read one original page of the current book edition.","description":"Public reading requires no account. Use exact returned URLs and keep one edition throughout a reading. A page or section is not the whole book; check scope, page and block counts, and end_of_document. Cite the supplied original-page citation_url.","parameters":[{"in":"path","name":"page_number","required":true,"schema":{"type":"integer","minimum":1},"description":"Use a page_files[].number returned by the selected book manifest."},{"in":"path","name":"format","required":true,"schema":{"type":"string","enum":["xml","json"]},"description":"Choose XML or JSON for the same authored source."}],"responses":{"200":{"description":"Complete selected source, with author and original citation metadata.","content":{"application/xml":{"schema":{"type":"string"}},"application/json":{"schema":{"type":"object"}}}},"404":{"description":"No public source exists at this address. Use a URL returned by the catalog or manifest.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/reader/book/editions/{release_id}/chapters/{section_id}.{format}":{"get":{"operationId":"readEditionBookSection","summary":"Read one section from an identified book edition.","description":"Public reading requires no account. Use exact returned URLs and keep one edition throughout a reading. A page or section is not the whole book; check scope, page and block counts, and end_of_document. Cite the supplied original-page citation_url.","parameters":[{"in":"path","name":"release_id","required":true,"schema":{"type":"string","pattern":"^[a-z0-9-]+$"},"description":"Use the release identifier from a returned immutable section or page URL."},{"in":"path","name":"section_id","required":true,"schema":{"type":"string","pattern":"^[a-z0-9-]+$"},"description":"Use a sections[].id returned by the selected book manifest."},{"in":"path","name":"format","required":true,"schema":{"type":"string","enum":["xml","json"]},"description":"Choose XML or JSON for the same authored source."}],"responses":{"200":{"description":"Complete selected source, with author and original citation metadata.","content":{"application/xml":{"schema":{"type":"string"}},"application/json":{"schema":{"type":"object"}}}},"404":{"description":"No public source exists at this address. Use a URL returned by the catalog or manifest.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/reader/book/editions/{release_id}/pages/{page_number}.{format}":{"get":{"operationId":"readEditionBookPage","summary":"Read one original page from an identified book edition.","description":"Public reading requires no account. Use exact returned URLs and keep one edition throughout a reading. A page or section is not the whole book; check scope, page and block counts, and end_of_document. Cite the supplied original-page citation_url.","parameters":[{"in":"path","name":"release_id","required":true,"schema":{"type":"string","pattern":"^[a-z0-9-]+$"},"description":"Use the release identifier from a returned immutable section or page URL."},{"in":"path","name":"page_number","required":true,"schema":{"type":"integer","minimum":1},"description":"Use a page_files[].number returned by the selected book manifest."},{"in":"path","name":"format","required":true,"schema":{"type":"string","enum":["xml","json"]},"description":"Choose XML or JSON for the same authored source."}],"responses":{"200":{"description":"Complete selected source, with author and original citation metadata.","content":{"application/xml":{"schema":{"type":"string"}},"application/json":{"schema":{"type":"object"}}}},"404":{"description":"No public source exists at this address. Use a URL returned by the catalog or manifest.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/reader/book/full.txt":{"get":{"operationId":"readCompleteBook_txt","summary":"Retrieve the entire approved textual book in txt. No signup. Verify completion using the manifest.","responses":{"200":{"description":"Complete source. A client tool may truncate its own output; verify all expected sections or use smaller files.","content":{"text/plain":{"schema":{"type":"string"}}}}}}},"/reader/book/full.md":{"get":{"operationId":"readCompleteBook_md","summary":"Retrieve the entire approved textual book in md. No signup. Verify completion using the manifest.","responses":{"200":{"description":"Complete source. A client tool may truncate its own output; verify all expected sections or use smaller files.","content":{"text/markdown":{"schema":{"type":"string"}}}}}}},"/reader/book/full.xml":{"get":{"operationId":"readCompleteBook_xml","summary":"Retrieve the entire approved textual book in xml. No signup. Verify completion using the manifest.","responses":{"200":{"description":"Complete source. A client tool may truncate its own output; verify all expected sections or use smaller files.","content":{"application/xml":{"schema":{"type":"string"}}}}}}},"/reader/book/full.json":{"get":{"operationId":"readCompleteBook_json","summary":"Retrieve the entire approved textual book in json. No signup. Verify completion using the manifest.","responses":{"200":{"description":"Complete source. A client tool may truncate its own output; verify all expected sections or use smaller files.","content":{"application/json":{"schema":{"type":"object"}}}}}}}},"components":{"schemas":{"Signup":{"type":"object","additionalProperties":false,"required":["request_id","email","offer_version","publication","authorized"],"properties":{"request_id":{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$","description":"One UUID version 4 per intended request. Reuse on retries for 24 hours. Retain it after an uncertain result."},"email":{"type":"string","format":"email","maxLength":254,"description":"One address selected by the reader. Never place it in a URL."},"offer_version":{"const":"daily-cup-2026-09-23-v1"},"publication":{"const":"daily-cup-of-craig-coffee"},"authorized":{"const":true,"description":"The client asserts a specific reader instruction; this is not cryptographic proof of consent."},"resubscribe_authorized":{"type":"boolean","default":false},"captcha_token":{"type":"string","maxLength":2048,"description":"A current token from the site’s actual challenge, when required. Never synthesize or bypass the challenge."}}},"Check":{"type":"object","additionalProperties":false,"required":["request_id","email"],"properties":{"request_id":{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$","description":"One UUID version 4 per intended request. Reuse on retries for 24 hours. Retain it after an uncertain result."},"email":{"type":"string","format":"email","maxLength":254,"description":"One address selected by the reader. Never place it in a URL."}}},"Receipt":{"type":"object","required":["request_id","request_status","subscription_status","email_delivery"],"properties":{"request_id":{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$","description":"One UUID version 4 per intended request. Reuse on retries for 24 hours. Retain it after an uncertain result."},"request_status":{"enum":["processed","checking"]},"subscription_status":{"const":"not_disclosed"},"email_delivery":{"const":"not_verified"},"next_step":{"type":"string"},"retry_after_seconds":{"type":"integer","minimum":1},"check":{"type":"string","format":"uri"},"book":{"type":"object"},"browser_signup":{"type":"string","format":"uri"}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$","description":"One UUID version 4 per intended request. Reuse on retries for 24 hours. Retain it after an uncertain result."},"retry_after_seconds":{"type":"integer"},"book":{"type":"object"},"browser_signup":{"type":"string"}}}}}}