---
title: "Search documentation across multiple libraries"
method: POST
path: "/v1/search"
tags: ["Search"]
---

# Search documentation across multiple libraries

`POST /v1/search`

Search one or more libraries. Returns scored section results.
Accepts library identifiers (e.g. `vercel/next.js`).

## Request body

- SearchRequest
  - `query` string, required — Natural-language search query. Capped at 2000 characters: longer queries don't improve retrieval quality (embedding models truncate well before that) and indicate a different problem (consider calling `read` to fetch a section and prompting your own LLM with the result).
  - `libraries` string[], required — One or more library identifiers (`owner/repo` form).
  - `limit` integer — Maximum number of section results to return (default 10, max 100).
  - `include_content` boolean — When `true` (default), returns each matched section's full content. When `false`, returns titles + URLs only (preview mode); follow up with `read(url)` for the body.

## Response `200`

Search results

- SearchResponse
  - `object` 'search_result', required
  - `results` SearchSection[], required
    - `id` string, required — Opaque section identifier. Useful for dedup across requests.
    - `score` number, required — Relevance score in [0, 1]. Higher is more relevant.
    - `title` string, required
    - `content` string, required — Section body. Empty string when `include_content` is `false` in the request.
    - `path` string, required — Source-relative file path (e.g. `docs/01-app/03-middleware.mdx`). Informational for citation; use `url` as the addressable handle to pass to `read`.
    - `url` string, uri, required — Addressable URL for this section. Pass to `read(url)` to fetch full content.
    - `start_line` integer, required
    - `end_line` integer, required
    - `parent_headers` string[], required — Heading-ancestry breadcrumb (e.g. `["Routing", "Middleware", "Authentication"]`). Useful for citation context without a second `read` call to reconstruct.
    - `library_identifier` string, required — Identifier of the library that produced this section (e.g. `vercel/next.js`). Cite this when surfacing results to users; matches the value in your `libraries` request array.
  - `meta` SearchMeta, required
    - `query` string, required — Echo of the input query.
    - `libraries` object, required — Identifier-level audit trail. `resolved` lists which of the requested `libraries[]` matched real catalog entries; `unresolved` lists the ones we couldn't match. Batch search succeeds partially: results come from `resolved`; consumers can surface "couldn't find: X" UX from `unresolved`.
      - `resolved` string[], required
      - `unresolved` string[], required
    - `usage` object, required — Billing-grade observability. `chunks_searched` is total candidates considered; `chunks_returned` is what made it through `limit`; `embedding_tokens` is the query embedding cost in tokens.
      - `chunks_searched` integer, required
      - `chunks_returned` integer, required
      - `embedding_tokens` integer, required
    - `performance` object, required — Server-side wall-clock timing. Excludes network round-trip.
      - `latency_ms` number, required

## Other responses

- `400` — Invalid request parameters
- `404` — Resource not found
- `500` — Internal server error

---

[API](https://skmtc.dev/docfork/apis/docfork-api.md) · [All operations](https://skmtc.dev/docfork/apis/docfork-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/docfork/docfork-api/revisions/00951adfafe4/schema)