Skip to content

For readers and software

Public API

Spreuke publishes its approved reading corpus and public-sale product catalog as static JSON under /api/v1/. These feeds are public, unauthenticated, and read-only.

Endpoint families

Catalog
/api/v1/catalog.json — Books, Sparks, and daily rotation order.
Approved products
/api/v1/products.json — The public product catalog used by the Spreuke shop and future discovery adapters.
Book
/api/v1/books/{slug}.json — Description, chapter index, Spark index, and cover.
Chapter
/api/v1/books/{slug}/chapters/{number}.json — Complete chapter text and reading position.
Spark
/api/v1/sparks/{slug}.json — Spark, walk-through, provenance, source, and share image.
Blog feed
/api/v1/blog.json — Index of approved posts.
Blog post
/api/v1/blog/{slug}.json — Complete approved post text.
Country echo
/api/v1/country — Raw Cloudflare country signal as text/plain; see the exception below.

Contract

Content endpoints return application/json. Version 1 is additive and its published URLs are permanent; a breaking contract would use /api/v2/.

Static content can be cached normally. /api/v1/country is the exception: it returns text/plain with Cache-Control: no-store and echoes Cloudflare's raw country signal. A missing signal produces an empty successful response. Callers must fail closed for advertising when the response is missing, empty, unknown, or an error.

The content and product-feed endpoints have no authentication, accounts, write actions, user state, or checkout logic. Product data includes only records explicitly approved for public sale. A product variant’s `available` field means it is enabled in this public catalog; it is not a live supplier-stock signal or a guarantee of current fulfillment availability. Supplier observations, when shown by browser discovery tools, are separately timestamped and become unknown when stale. Checkout is a separate service and no Shopify, ACP, or agent purchase eligibility is implied by the feed.

Machine descriptions

Read the OpenAPI 3.1 document or the RFC 9727 API catalog.