Catalog API v1

Read published authors, books and approved articles. No application login, application cookies or API key required.

This production API is publicly readable without login or API keys. All responses are private/no-store and noindex. No cross-origin access is enabled.

API root OpenAPI 3.1.2 document

Endpoints

GET /api/v1 — version and discovery links.
GET /api/v1/authors — collection; /api/v1/authors/{id} — one published record.
GET /api/v1/books — collection; /api/v1/books/{id} — one published record.
GET /api/v1/articles — collection; /api/v1/articles/{id} — one published record.

HEAD is supported on all GET routes with the same status/headers and no response body. Other methods, including OPTIONS, return JSON 405 with Allow: GET, HEAD. No mutations or credentialed CORS are provided.

Stable identifiers and fields

Resource IDs are decimal strings for stable catalog/article IDs, not authentication-account IDs. Slugs are secondary lookup keys. Imported legacy_ids are retained as strings, empty for manually created records. Absolute links use this application's configured trusted URL. Absent optional values are JSON null; absent collections are empty arrays. Dates use YYYY-MM-DD; no creation/update/review timestamps are exposed.

Authors include published biographies, photograph/alt, public website/social links and bounded published work references. Books include plain/safe-HTML descriptions, ordered contributors with roles/zero-based positions, cover/alt, optional ISBNs, format text, release date in the existing publication_date field, boolean featured status, purchase links, sample and related articles. Articles include the published revision's title/subtitle/excerpt/body, byline and author references, date, images/alt/captions, PDF, conversation links and public related catalog references.

Formatted text objects explicitly label plain_text and safe html. Article bodies have plain text and typed paragraph/heading/quote/image/list blocks. Captions are plain text. PDFs use controlled attachment URLs. Internal review/editing notes, account details and private storage information are excluded. No prices or missing bibliography are invented. Unavailable/private local links are omitted as links, while their plain text remains. External approved http/https links are retained; known legacy local pages/assets resolve to eligible development routes.

Assigned book ISBNs

isbn10 and isbn13 retain their string/null types; the paperback ISBN stays in isbn13. ISBNs beginning with 979 have no ISBN-10 equivalent. The additive editions array contains format (Paperback, Hardback or EPUB), isbn10 and isbn13 string/null fields. An empty array means no assigned edition identifiers. These assignments do not imply stock, a purchase offer or format availability. Existing formats remains free text/null and is preserved independently. REST collections/details and MCP search_books/get_book share this representation.

Pagination, search and filters

page: 1–10000, default 1. Out-of-data pages return an empty collection.
per_page: 1–100, default 25.
q: At most 100 UTF-8 characters; literal substring search. Authors: name and biographies. Books: title, subtitle, description. Articles: approved title, subtitle, excerpt and byline (not body or private metadata).
slug: Exact lowercase hyphenated slug, at most 160 characters.
author_id: Books/articles only: published contributor or approved author relationship, including an article's byline author. Nonpublic/unknown IDs produce an empty collection.
sort: catalog (default), id ascending or -id descending. Default books order: featured first, known release date descending, unknown dates last within each group, then ascending stable book ID. Authors retain display order then descending stable ID; articles use approved display order, descending publication date, then ascending ID.

Unknown, repeated, array-valued, malformed and out-of-range parameters return 400. Detail and root routes accept no query parameters. Collections return data, meta (page, per_page, total, total_pages) and links (self, next, previous). Empty totals have zero pages. Pagination is offset-based: each response uses one consistent database read snapshot, but later requests may shift after publication changes; restart traversal if needed.

Nested references never expand recursively. Book work/related references use the same default book order. Article references retain their established ordering. Work/article references are capped at 25 per relationship, with deterministic ordering; collection links provide full traversal. Contributors are ordered by position (at most 100); article related records are capped at 100 (normal editing allows at most 30 per kind). Only independently public relationships and eligible assets are returned.

Publication and privacy

A published book requires published contributors. Articles read only their designated approved/legacy-published revision. A newer draft, submission, withdrawal or request for changes never changes the live API content or assets. Approval atomically switches the published revision. Nonpublic IDs return the same 404 as nonexistent IDs, even with owner cookies. Unpublish/archive removes API access; shared assets remain available only while another live record legitimately references them.

Limits and errors

Current limit: 60 requests per 60 seconds per client address, shared across API and documentation routes, including HEAD/errors. Only configured trusted proxies affect address selection. A 429 includes remaining-window Retry-After seconds; counters are separate from login limits. Runtime configuration uses Config\CatalogApi. No application session is started.

Success: {"data": ...}. Error: {"error":{"code":"not_found","message":"Resource not found."}}. Statuses: 400 invalid parameters, 404 absent/nonpublic, 405 unsupported method, 429 rate limit, 503 temporary service failure. The OpenAPI route returns the specification document directly. The outer development gate may return Apache HTML 401 before the application runs.

Local curl examples

No credentials or application cookies are required.

curl 'https://vinemakerpublishing.com/api/v1/books?per_page=25'
curl 'https://vinemakerpublishing.com/api/v1/articles?q=faith'
curl 'https://vinemakerpublishing.com/api/v1/authors?slug=nina-cesena'
curl --head 'https://vinemakerpublishing.com/api/v1'
curl 'https://vinemakerpublishing.com/api/openapi.json'

Back to catalog