---
title: "Ranked catalog search"
method: GET
path: "/search"
---

# Ranked catalog search

`GET /search`

## Request

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

Field-weighted full-text search over titles, subtitles, named concepts, concept questions and answers, descriptions, series names, and chapter titles. Results are ranked by relevance score.

## Query parameters

- `q` string, required
- `series` 'the-operators-ai-library' | 'the-ai-native-builder-canon' | 'understand-and-trust-ai' | 'build-agents-you-can-trust' | 'lead-govern-and-apply-ai' | 'ai-and-agentic-engineering' | 'the-claude-code-ladder' | 'the-agent-builders-workshop' | 'the-two-doors' | 'forward-deployed-engineering-handbooks' | 'the-complete-grok-bot-guide' | 'the-omarchy-books' | 'the-personal-ai-computer'
- `audience` 'beginner' | 'operator' | 'engineer' | 'leader'
- `limit` integer

## Response `200`

Ranked results

- 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
    - `series` string, nullable
    - `audience` string, nullable
    - `limit` integer
  - `count` integer
  - `totalMatches` integer
  - `results` SearchResult[]
    - `score` number: Relevance score. Higher is better.
    - `matchedFields` string[]: Which fields the query matched.
    - `book` object
      - `slug` string
      - `title` string
      - `subtitle` string, nullable
      - `author` string, nullable
      - `readerLevel` 'beginner' | 'operator' | 'engineer' | 'leader'
      - `series` object, nullable
        - `name` string
        - `slug` string
      - `oneLiner` string, nullable
      - `url` string, uri
      - `apiUrl` string, uri
      - `coverImage` string, uri, nullable

## Other responses

- `400`: Missing or empty q, unknown series or audience, 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)