Greenlit Books Catalog API

openapi: 3.2.0
info:
  title: Greenlit Books Catalog API
  version: 1.2.0
  description: 'Public read-only JSON API for the Greenlit Books catalog: practical books on working with AI, all live on Amazon and free to read with Kindle Unlimited. Every endpoint is a plain HTTP GET returning pretty-printed JSON with a meta envelope. Amazon links are clean /dp/ URLs. The catalog intentionally omits publication dates, page counts, and ISBNs because it carries no verified source for them; nothing is invented. Human documentation: https://greenlitbooks.com/developers'
  contact:
    name: Greenlit Books
    url: https://greenlitbooks.com
servers:
- url: https://greenlitbooks.com/api/v1
security: []
tags:
- name: Catalog
paths:
  /catalog:
    get:
      operationId: getCatalog
      summary: The whole catalog in one response
      description: 'One-shot dump for agents that prefer a single ingestion: every book at detail depth plus series, imprints, and concepts.'
      responses:
        '200':
          description: The full catalog
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/Meta'
                  publisher:
                    type: object
                    properties:
                      name:
                        type: string
                      url:
                        type: string
                        format: uri
                      description:
                        type: string
                  counts:
                    type: object
                    properties:
                      books:
                        type: integer
                      series:
                        type: integer
                      concepts:
                        type: integer
                      topics:
                        type: integer
                      terms:
                        type: integer
                  series:
                    type: array
                    items:
                      $ref: '#/components/schemas/Series'
                  imprints:
                    type: array
                    items:
                      $ref: '#/components/schemas/Imprint'
                  books:
                    type: array
                    items:
                      $ref: '#/components/schemas/BookDetail'
                  concepts:
                    type: array
                    items:
                      $ref: '#/components/schemas/Concept'
                  terms:
                    type: array
                    items:
                      $ref: '#/components/schemas/Term'
      tags:
      - Catalog
components:
  schemas:
    Series:
      type: object
      properties:
        name:
          type: string
        slug:
          type: string
        tier:
          type: string
          description: Short audience label.
        blurb:
          type: string
        order:
          type: integer
          description: Curated shelf order.
        count:
          type: integer
        url:
          type: string
          format: uri
        apiUrl:
          type: string
          format: uri
        books:
          type: array
          items:
            $ref: '#/components/schemas/BookLink'
    Price:
      type:
      - object
      - 'null'
      description: Price for one format. amount is parsed from the display string.
      properties:
        display:
          type: string
          examples:
          - $12.99
        amount:
          type:
          - number
          - 'null'
          examples:
          - 12.99
        currency:
          type:
          - string
          - 'null'
          examples:
          - USD
    HandoffLinks:
      type: object
      description: Where to send a reader next. freeChapter is the complete chapter one, free; Amazon links are bare /dp/ URLs; citeAs is a ready citation line.
      properties:
        glossary:
          type:
          - string
          - 'null'
          format: uri
        glossaryMarkdown:
          type:
          - string
          - 'null'
          format: uri
        concept:
          type:
          - string
          - 'null'
          format: uri
        conceptMarkdown:
          type:
          - string
          - 'null'
          format: uri
        book:
          type: string
          format: uri
        bookApi:
          type: string
          format: uri
        bookMarkdown:
          type: string
          format: uri
        freeChapter:
          type:
          - string
          - 'null'
          format: uri
        freeChapterMarkdown:
          type:
          - string
          - 'null'
          format: uri
        amazonKindle:
          type:
          - string
          - 'null'
          format: uri
        amazonPaperback:
          type:
          - string
          - 'null'
          format: uri
        kindleUnlimited:
          type: boolean
        citeAs:
          type: string
    Term:
      type: object
      properties:
        slug:
          type: string
        term:
          type: string
        aliases:
          type: array
          items:
            type: string
        kind:
          type: string
          enum:
          - coined
          - operational
          description: 'coined: the house minted the phrase. operational: an industry term whose AI-agent definition the home book supplies.'
        fieldOfOrigin:
          type:
          - string
          - 'null'
        definition:
          type: string
          description: The book's own sentence, verbatim.
        definedIn:
          type: object
          properties:
            book:
              $ref: '#/components/schemas/BookLink'
            chapter:
              type: string
            source:
              type: string
              enum:
              - bible
              - manuscript
        usedInBooks:
          type: array
          items:
            $ref: '#/components/schemas/BookLink'
        checkable:
          type: object
          properties:
            claim:
              type: string
            howToCheck:
              type: string
        faq:
          type: array
          items:
            type: object
            properties:
              q:
                type: string
              a:
                type: string
        relatedTerms:
          type: array
          items:
            type: object
            properties:
              slug:
                type: string
              term:
                type: string
              url:
                type: string
                format: uri
              apiUrl:
                type: string
                format: uri
        url:
          type: string
          format: uri
        markdownUrl:
          type: string
          format: uri
        apiUrl:
          type: string
          format: uri
        lastVerified:
          type: string
          format: date
        links:
          $ref: '#/components/schemas/HandoffLinks'
    Meta:
      type: object
      description: Envelope on every response.
      properties:
        version:
          type: string
          const: v1
        generatedAt:
          type: string
          format: date-time
          description: When this snapshot was produced. Static endpoints stamp it at deploy; search stamps it per request.
        source:
          type: string
          format: uri
        docs:
          type: string
          format: uri
        openapi:
          type: string
          format: uri
    BookDetail:
      type: object
      description: The /books/{slug} response body.
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        book:
          $ref: '#/components/schemas/Book'
        chapters:
          type: array
          items:
            type: object
            properties:
              number:
                type: integer
              title:
                type: string
        totalWords:
          type:
          - integer
          - 'null'
        claims:
          type:
          - object
          - 'null'
          description: 'Quotable claims from the book with the sources behind them, or null for a book with no ledger yet. Each item''s `url` is an anchor on the book page that resolves to that exact claim: quote `claim`, cite `url`.'
          properties:
            lastReviewed:
              type: string
              format: date
            items:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                  chapter:
                    type: integer
                  claim:
                    type: string
                  verbatim:
                    type: boolean
                    description: True when `claim` is the book's own sentence, word for word.
                  basis:
                    type: string
                    enum:
                    - external
                    - argument
                    - method
                    - author-experience
                    description: What kind of statement this is. A published result, a position the book argues, a method you run yourself, or something the author reports happening on his own system. They are not interchangeable and should not be quoted as if they were.
                  basisLabel:
                    type: string
                  howToQuote:
                    type: string
                  basisNote:
                    type:
                    - string
                    - 'null'
                  anchor:
                    type: string
                  url:
                    type: string
                    format: uri
                  sources:
                    type: array
                    items:
                      type: object
                      properties:
                        title:
                          type: string
                        authors:
                          type:
                          - string
                          - 'null'
                        publisher:
                          type:
                          - string
                          - 'null'
                        date:
                          type:
                          - string
                          - 'null'
                        url:
                          type: string
                          format: uri
                        establishes:
                          type: string
                        doesNotEstablish:
                          type: string
                          description: What the claim would be overreaching to draw from this source. Read it before leaning on the citation.
                        lastChecked:
                          type: string
                          format: date
                        checkNote:
                          type:
                          - string
                          - 'null'
        excerpt:
          type: object
          description: The free chapter-one excerpt, when published.
          properties:
            available:
              type: boolean
            chapterTitle:
              type:
              - string
              - 'null'
            words:
              type:
              - integer
              - 'null'
            minutes:
              type:
              - integer
              - 'null'
            url:
              type:
              - string
              - 'null'
              format: uri
            markdownUrl:
              type:
              - string
              - 'null'
              format: uri
        related:
          type: object
          properties:
            guide:
              type:
              - object
              - 'null'
              properties:
                title:
                  type: string
                slug:
                  type: string
                url:
                  type: string
                  format: uri
            fieldNotes:
              type: array
              items:
                type: object
                properties:
                  title:
                    type: string
                  slug:
                    type: string
                  description:
                    type: string
                  url:
                    type: string
                    format: uri
            compares:
              type: array
              items:
                type: object
                properties:
                  title:
                    type: string
                  slug:
                    type: string
                  url:
                    type: string
                    format: uri
            seriesNeighbors:
              type: object
              properties:
                previous:
                  oneOf:
                  - $ref: '#/components/schemas/BookLink'
                  - type: 'null'
                next:
                  oneOf:
                  - $ref: '#/components/schemas/BookLink'
                  - type: 'null'
    Imprint:
      type: object
      description: An imprint groups books across one or more series.
      properties:
        name:
          type: string
        count:
          type: integer
        series:
          type: array
          items:
            type: string
          description: Slugs of the series this imprint spans.
    Book:
      type: object
      description: 'One book. No publication date, page count, or ISBN: the catalog carries no verified source for them and nothing is invented. Amazon URLs are clean /dp/ links; every listed book is buyable there and free to read with Kindle Unlimited when kindleUnlimited is true.'
      properties:
        slug:
          type: string
        title:
          type: string
        subtitle:
          type:
          - string
          - 'null'
        author:
          type:
          - string
          - 'null'
        series:
          type:
          - object
          - 'null'
          properties:
            name:
              type: string
            slug:
              type: string
            position:
              type: integer
              description: 1-based reading order within the series.
        imprint:
          type:
          - string
          - 'null'
        readerLevel:
          type: string
          enum:
          - beginner
          - operator
          - engineer
          - leader
        flagship:
          type: boolean
        descriptions:
          type: object
          properties:
            hook:
              type:
              - string
              - 'null'
              description: A quotable opening line.
            oneLiner:
              type:
              - string
              - 'null'
              description: Short description.
            targetReader:
              type:
              - string
              - 'null'
              description: Who the book is for.
            namedConcept:
              type:
              - string
              - 'null'
              description: The named idea the book teaches.
        concept:
          type:
          - object
          - 'null'
          description: The question-shaped concept page for this book.
          properties:
            name:
              type: string
            slug:
              type: string
            question:
              type: string
            url:
              type: string
              format: uri
        amazon:
          type: object
          properties:
            kindleAsin:
              type:
              - string
              - 'null'
            paperbackAsin:
              type:
              - string
              - 'null'
            kindleUrl:
              type:
              - string
              - 'null'
              format: uri
            paperbackUrl:
              type:
              - string
              - 'null'
              format: uri
        prices:
          type: object
          properties:
            ebook:
              $ref: '#/components/schemas/Price'
            paperback:
              $ref: '#/components/schemas/Price'
        kindleUnlimited:
          type: boolean
        coverImage:
          type:
          - string
          - 'null'
          format: uri
        url:
          type: string
          format: uri
          description: Canonical book page.
        apiUrl:
          type: string
          format: uri
        markdownUrl:
          type: string
          format: uri
          description: Plain-markdown twin of the book page.
        readUrl:
          type:
          - string
          - 'null'
          format: uri
          description: Free chapter one, when available.
        categories:
          type: array
          items:
            type: string
        companionRepo:
          type:
          - string
          - 'null'
          format: uri
          description: Public companion code repository, when the book ships code.
    Concept:
      type: object
      properties:
        name:
          type: string
        slug:
          type: string
        question:
          type: string
        shortAnswer:
          type: string
        url:
          type: string
          format: uri
        markdownUrl:
          type: string
          format: uri
          description: Markdown twin with the full body and FAQ.
        book:
          $ref: '#/components/schemas/BookLink'
    BookLink:
      type: object
      description: Compact pointer to a book, with its reading-order position in its series.
      properties:
        slug:
          type: string
        title:
          type: string
        position:
          type: integer
          description: 1-based reading order within the series.
        url:
          type: string
          format: uri
        apiUrl:
          type: string
          format: uri
externalDocs:
  description: Human documentation, the MCP server, and the markdown surfaces for agents
  url: https://greenlitbooks.com/developers