---
title: "Find the claim that bears on what you are about to assert"
method: GET
path: "/claims/search"
---

# Find the claim that bears on what you are about to assert

`GET /claims/search`

## Request

- Base URL: `https://greenlitbooks.com/api/v1`
- URL: `https://greenlitbooks.com/api/v1/claims/search`
- Auth: none required

Ranked search over the claim ledger: the claim sentences themselves, the titles of their sources, what each source establishes, and the book titles, matched by their words and by their meaning, so a whole sentence in your own words works as a query. Use this rather than downloading the whole ledger when you have one thing to check. Every result arrives with its basis, its sources including what they do not establish, and a citation already written that carries the link.

## Query parameters

- `q` string, required
- `basis` 'external' | 'argument' | 'method' | 'author-experience'
- `book` string
- `limit` integer

## Response `200`

Ranked claims

- object
  - `meta` Meta: Envelope on every response.
    - `version` 'v1'
    - `generatedAt` string, date-time: When this snapshot was produced. Static endpoints stamp it at deploy; search stamps it per request.
    - `source` string, uri
    - `docs` string, uri
    - `openapi` string, uri
  - `query` object
    - `q` string
    - `terms` string[]: 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` 'words+meaning' | 'words': 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` string, nullable
    - `book` string, nullable
    - `limit` integer
  - `count` integer
  - `totalMatches` integer
  - `reason` string: 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` string: What a caller should understand about a result before quoting it.
  - `license` object: The licence these records are published under.
    - `name` string
    - `url` string, uri
    - `attribution` string
    - `covers` string
  - `results` ClaimSearchResult[]
    - `score` number: Word relevance, comparable with /search scores. 0 when the claim was found by meaning alone.
    - `matchedFields` string[]
    - `matchedTerms` integer: 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` string[]: 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` number, nullable: 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` Claim: One quotable claim with a stable citation URL.
      - `id` string
      - `url` string, uri: The fragment to cite. Stable: an id is never reworded in place.
      - `anchor` string
      - `chapter` integer
      - `claim` string
      - `verbatim` boolean: True when this is the book's own sentence.
      - `basis` 'external' | 'argument' | 'method' | 'author-experience': What kind of statement this is. The four are not interchangeable.
      - `basisLabel` string
      - `quotingRule` string: How this basis may honestly be quoted.
      - `basisNote` string
      - `citation` Citation: 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.
        - `url` string, uri: The fragment the citation points at.
        - `text` string: 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` string: Ready to paste into a .bib file.
        - `key` string: The BibTeX key on its own, for citing in LaTeX.
      - `sources` ClaimSource[]
        - `title` string
        - `authors` string, nullable
        - `publisher` string, nullable
        - `date` string, nullable: Whatever date the source itself states.
        - `url` string, uri
        - `establishes` string
        - `doesNotEstablish` string
        - `lastChecked` string, date
        - `checkNote` string: Present when the check was indirect, naming how it was made.
      - `book` BookLink: Compact pointer to a book, with its reading-order position in its series.
        - `slug` string
        - `title` string
        - `position` integer: 1-based reading order within the series.
        - `url` string, uri
        - `apiUrl` string, uri

## Other responses

- `400`: Missing or empty q, unknown basis, or invalid limit

---

[API](https://skmtc.dev/greenlitbooks/apis/greenlit-books-api.md) · [All operations](https://skmtc.dev/greenlitbooks/apis/greenlit-books-api/llms.txt) · [OpenAPI document](https://skmtc.dev/greenlitbooks/apis/greenlit-books-api/revisions/7c8b9f94ca1e?raw)