# Search the docs

Source: https://workroad.app/docs/api/search-docs

`GET https://workroad.app/api/v1/docs/search`

Searches the WorkRoad docs: the guides to each part of the app, the REST API guide, the MCP server guide and the reference page of every operation. Use it when the user asks how WorkRoad works, how to do something in the app, or how to use the API, then read a page with `getDoc`. Pages come best match first, each with the passages that matched. Any key may call it.

- MCP tool: `searchDocs` on `https://workroad.app/api/mcp`
- Required scopes: None beyond a valid key.
- Test mode: `GET https://workroad.app/api/test/v1/docs/search` checks the request and returns the example response without changing anything.
- Next: read the best page with `getDoc` and its `slug`.

## Query parameters

- `q`: string, required, 1-200 characters. Words to look for, 1-200 characters, such as `practice flashcards`.
- `locale`: one of `"en"`, `"de"`, `"es"`, `"fr"`, `"it"`. The docs' language: `en`, `de`, `es`, `fr`, `it`. Defaults to `en`. A page with no translation, such as an API reference page, comes back in English.
- `limit`: integer, 1 to 20, default `5`. Pages to return, 1-20.

## Response

`200` OK

- `data`: array of objects, required
  - `title`: string, required
  - `description`: string or null, required. The page's summary, when it has one.
  - `slug`: string, required. The page's `slug` for `getDoc`.
  - `url`: string, required. The page on the docs site.
  - `markdownUrl`: string, required. The same page as Markdown, readable without a key.
  - `snippets`: array of objects, required. Up to three passages of the page that match, best first.
    - `text`: string, required. A matching heading or passage.
    - `url`: string, required. The page, scrolled to that passage.

### Example

```json
{
  "data": [
    {
      "title": "Studying",
      "description": "Study sets, take tests, use the feed, and check performance.",
      "slug": "studying",
      "url": "https://workroad.app/docs/studying",
      "markdownUrl": "https://workroad.app/docs/studying.md",
      "snippets": [
        {
          "text": "Study a set",
          "url": "https://workroad.app/docs/studying#study-a-set"
        }
      ]
    }
  ]
}
```

## Errors

Every error has the body `{ "error": { "code", "message", "details" } }`.

- `400`: Invalid request body or query
- `401`: Missing, invalid, disabled or expired API key
- `403`: The API key lacks the required scope
- `404`: No endpoint exists at this path.
- `405`: Method not allowed. Use a method from the Allow header.
- `429`: Rate limit exceeded. Wait for Retry-After before retrying. The rate-limit headers are absent when the key's own limiter rejected the request before the per-endpoint bucket check ran.
- `500`: Internal server error