Greenlit Books Claims API

openapi: 3.2.0
info:
  title: Greenlitbooks Com Claims API
  version: 1.2.0
  contact:
    name: Greenlit Books
    url: https://greenlitbooks.com
  description: 'Operations tagged Claims across 2 of this provider''s published API definitions: greenlitbooks-com-openapi-gpt.json, greenlitbooks-com-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://greenlitbooks.com/api/v1
security: []
tags:
- name: Claims
paths:
  /claims/search:
    get:
      operationId: searchClaims
      summary: Find the claim that bears on what you are about to assert
      description: Check a statement against the books' claim ledger. Returns claims bearing on it, each with a ready citation and what its source does not establish.
      parameters:
      - name: q
        in: query
        required: true
        schema:
          type: string
        description: The search query. Required and non-empty.
        example: long context accuracy
      - name: basis
        in: query
        required: false
        schema:
          type: string
          enum:
          - external
          - argument
          - method
          - author-experience
        description: Restrict results to one kind of statement. basis=external returns only claims resting on a published result.
      - name: book
        in: query
        required: false
        schema:
          type: string
        description: Restrict results to one book, by slug.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 25
          default: 10
        description: Maximum number of results.
      responses:
        '200':
          description: Ranked claims
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/Meta'
                  query:
                    type: object
                    properties:
                      q:
                        type: string
                      terms:
                        type: array
                        items:
                          type: string
                        description: The query after words too common across the ledger to distinguish one claim from another are dropped. This is what was actually searched for. Empty means the query was all filler.
                      matching:
                        type: string
                        enum:
                        - words+meaning
                        - words
                        description: words+meaning normally. words alone means the embedding model could not be loaded for this request, and the results are what a word match finds.
                      basis:
                        type:
                        - string
                        - 'null'
                      book:
                        type:
                        - string
                        - 'null'
                      limit:
                        type: integer
                  count:
                    type: integer
                  totalMatches:
                    type: integer
                  reason:
                    type: string
                    description: 'Present only when there are no results, saying why: the query held no searchable words, every word was too common to search on, or no claim accounted for enough of it. An empty result is an answer, not a failure.'
                  howToQuote:
                    type: string
                    description: What a caller should understand about a result before quoting it.
                  license:
                    type: object
                    description: The licence these records are published under.
                    properties:
                      name:
                        type: string
                      url:
                        type: string
                        format: uri
                      attribution:
                        type: string
                      covers:
                        type: string
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/ClaimSearchResult'
        '400':
          description: Missing or empty q, unknown basis, or invalid limit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Claims
    servers:
    - url: https://greenlitbooks.com/api/v1
  /claims:
    get:
      operationId: listClaims
      summary: 'The claim ledger: every quotable claim with its basis and sources'
      description: One export of the whole claim ledger. Each claim carries a stable citation URL pointing at the exact fragment on the book page, whether the sentence is the book's own words, what kind of statement it is, and the one-line rule for quoting that kind honestly. Each external source states both what it establishes and what it does not, so a claim cannot be laundered through a real URL. Coverage is partial and the response says so.
      responses:
        '200':
          description: The claim ledger
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/Meta'
                  counts:
                    type: object
                    properties:
                      books:
                        type: integer
                      claims:
                        type: integer
                      sources:
                        type: integer
                      byBasis:
                        type: object
                        additionalProperties:
                          type: integer
                  license:
                    type: object
                    description: The licence the claim records are published under, and what it covers.
                    properties:
                      name:
                        type: string
                      url:
                        type: string
                        format: uri
                      attribution:
                        type: string
                      covers:
                        type: string
                  coverage:
                    type: string
                    description: Which books this export does and does not cover, and why.
                  dataset:
                    type: object
                    description: This export described as a schema.org Dataset, for anyone cataloguing or republishing it. The same node the developers page renders.
                    additionalProperties: true
                  books:
                    type: array
                    items:
                      $ref: '#/components/schemas/ClaimBook'
      tags:
      - Claims
    servers:
    - url: https://greenlitbooks.com/api/v1
components:
  schemas:
    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
    Claim:
      type: object
      description: One quotable claim with a stable citation URL.
      properties:
        id:
          type: string
        url:
          type: string
          format: uri
          description: 'The fragment to cite. Stable: an id is never reworded in place.'
        anchor:
          type: string
        chapter:
          type: integer
        claim:
          type: string
        verbatim:
          type: boolean
          description: True when this is the book's own sentence.
        basis:
          type: string
          enum:
          - external
          - argument
          - method
          - author-experience
          description: What kind of statement this is. The four are not interchangeable.
        basisLabel:
          type: string
        quotingRule:
          type: string
          description: How this basis may honestly be quoted.
        basisNote:
          type: string
        citation:
          $ref: '#/components/schemas/Citation'
        sources:
          type: array
          items:
            $ref: '#/components/schemas/ClaimSource'
        book:
          $ref: '#/components/schemas/BookLink'
    ClaimSource:
      type: object
      description: 'One external source behind a claim. Both halves are required: what a reader who opens this URL will find, and what the claim would be overreaching to draw from it.'
      properties:
        title:
          type: string
        authors:
          type:
          - string
          - 'null'
        publisher:
          type:
          - string
          - 'null'
        date:
          type:
          - string
          - 'null'
          description: Whatever date the source itself states.
        url:
          type: string
          format: uri
        establishes:
          type: string
        doesNotEstablish:
          type: string
        lastChecked:
          type: string
          format: date
        checkNote:
          type: string
          description: Present when the check was indirect, naming how it was made.
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              examples:
              - not_found
              - missing_query
            message:
              type: string
        meta:
          $ref: '#/components/schemas/Meta'
    ClaimSearchResult:
      type: object
      description: One matching claim, with why it matched.
      properties:
        score:
          type: number
          description: Word relevance, comparable with /search scores. 0 when the claim was found by meaning alone.
        matchedFields:
          type: array
          items:
            type: string
        matchedTerms:
          type: integer
          description: How many of query.terms this claim's words account for. A claim found by its words accounts for a strict majority of them, so a partial match is visible as one rather than reading as an exact answer.
        matchedBy:
          type: array
          items:
            type: string
            enum:
            - words
            - meaning
          description: 'How the claim was found. words: it accounts for most of the query''s terms. meaning: its sentence says something close to the query in other words, and shares at least two distinctive words with it. Both is the strongest.'
        similarity:
          type:
          - number
          - 'null'
          description: Closeness in meaning between the query and the claim sentence, from 0 to 1. Results are ordered by it when it is present. Null when meaning was unavailable for the request.
        claim:
          $ref: '#/components/schemas/Claim'
    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
    Citation:
      type: object
      description: The citation for this claim, already written, in the forms people paste. Both carry the fragment URL, so a quote taken from this export attributes itself.
      properties:
        url:
          type: string
          format: uri
          description: The fragment the citation points at.
        text:
          type: string
          description: Ready to paste into prose. The same string the book page renders. It ends with the date the record was last reviewed rather than an access date, because a build-time access date would describe when the page was generated, not when it was read.
        bibtex:
          type: string
          description: Ready to paste into a .bib file.
        key:
          type: string
          description: The BibTeX key on its own, for citing in LaTeX.
    ClaimBook:
      type: object
      description: One book's claim ledger.
      properties:
        slug:
          type: string
        title:
          type: string
        url:
          type: string
          format: uri
        apiUrl:
          type: string
          format: uri
        lastReviewed:
          type: string
          format: date
        claims:
          type: array
          items:
            $ref: '#/components/schemas/Claim'
externalDocs:
  description: Human documentation, the MCP server, and the markdown surfaces for agents
  url: https://greenlitbooks.com/developers
x-refined-from:
- greenlitbooks-com-openapi-gpt.json
- greenlitbooks-com-openapi.json