---
title: Endpoint de pesquisa
description: "Referência da API do endpoint de pesquisa do Jamdesk Docs (POST /_api/search): parâmetros, corpo, esquema de resposta e exemplos de código."
openapi: /openapi/docs-search-api.yaml POST /_api/search
---
> **For AI agents:** the complete documentation index is at [llms.txt](https://jamdesk.com/docs/llms.txt). Append `.md` to any page URL for its markdown version.

`POST https://jamdesk.com/docs/_api/search`

Performs semantic vector search across your project documentation and
returns matching pages ranked by relevance score.

Queries are embedded into the same vector space used to index your docs,
so the search understands intent — not just keywords. Ask a full
natural-language question for best results.

**Response shape:** an array of results (title, section, slug, content
snippet, URL, score), along with the original query, total count, and
search duration. The snippet field is capped at 500 characters and is
directly usable as LLM context.

**Typical latency:** 50-200ms for queries against projects under 10k
pages. Latency scales sub-linearly with index size.

## Authentication

- `BearerAuth` — http bearer

## Request body

- Content type: `application/json`
  - request body (object)
    - `query` (string, required) — Natural language search query.
    - `limit` (integer, default: 5) — Maximum number of results to return.
    - `language` (string, default: "en") — BCP-47 language code (e.g. `en`, `es`, `pt-BR`; 3-segment tags like `zh-Hant-HK` are not supported). Filters results to that language on multi-language projects; ignored on single-language projects. Default `en`.

## Response 200

Search results
  - response (object)
    - `results` (array)
      - `items` (object)
        - `title` (string) — Page title.
        - `section` (string) — Section heading within the page (if applicable).
        - `slug` (string) — URL path to the page.
        - `content` (string) — Content snippet (max 500 chars).
        - `url` (string, uri) — Full URL to the page.
        - `score` (number, float) — Relevance score (cosine similarity, 0.0–1.0). Higher is better.
    - `query` (string) — The query that was searched.
    - `language` (string) — Resolved language. Echoes the request value, defaulting to `en` when the request omitted the field.
    - `total` (integer) — Number of results returned.
    - `durationMs` (integer) — Server-side search execution time in milliseconds (excludes network round-trip).

## Response 400

Invalid request
  - response (object)
    - `error` (string) — Error detail. Authentication (401), authorization (403), and backend-outage (503) responses return a stable machine-readable code (e.g. `invalid_key`, `wrong_project`, `lookup_failed`) so clients can branch on the value. Request-validation (400), rate-limit (429), and search-unavailable (502) responses currently return a human-readable sentence.

## Response 401

Invalid or missing API key. The response body contains a
machine-readable `error` code: `invalid_key_format` (missing
or malformed — e.g. not `jd_live_<32 hex>`, 40 chars) or
`invalid_key` (key is not recognised or has been revoked).
  - response (object)
    - `error` (string) — Error detail. Authentication (401), authorization (403), and backend-outage (503) responses return a stable machine-readable code (e.g. `invalid_key`, `wrong_project`, `lookup_failed`) so clients can branch on the value. Request-validation (400), rate-limit (429), and search-unavailable (502) responses currently return a human-readable sentence.

## Response 403

API key does not match this project. The key is valid but was
generated for a different project slug than the one in the URL.
  - response (object)
    - `error` (string) — Error detail. Authentication (401), authorization (403), and backend-outage (503) responses return a stable machine-readable code (e.g. `invalid_key`, `wrong_project`, `lookup_failed`) so clients can branch on the value. Request-validation (400), rate-limit (429), and search-unavailable (502) responses currently return a human-readable sentence.

## Response 429

Rate limit exceeded
  - response (object)
    - `error` (string) — Error detail. Authentication (401), authorization (403), and backend-outage (503) responses return a stable machine-readable code (e.g. `invalid_key`, `wrong_project`, `lookup_failed`) so clients can branch on the value. Request-validation (400), rate-limit (429), and search-unavailable (502) responses currently return a human-readable sentence.

## Response 502

Search temporarily unavailable
  - response (object)
    - `error` (string) — Error detail. Authentication (401), authorization (403), and backend-outage (503) responses return a stable machine-readable code (e.g. `invalid_key`, `wrong_project`, `lookup_failed`) so clients can branch on the value. Request-validation (400), rate-limit (429), and search-unavailable (502) responses currently return a human-readable sentence.

## Response 503

Temporary backend outage during key verification. Returned when
the Redis lookup fails or the auth store is unreachable — retry
after a short backoff. The response body contains a
machine-readable `error` code: `lookup_failed` or
`redis_unavailable`.
  - response (object)
    - `error` (string) — Error detail. Authentication (401), authorization (403), and backend-outage (503) responses return a stable machine-readable code (e.g. `invalid_key`, `wrong_project`, `lookup_failed`) so clients can branch on the value. Request-validation (400), rate-limit (429), and search-unavailable (502) responses currently return a human-readable sentence.


---

📦 **OpenAPI specs:** Every OpenAPI specification referenced by this documentation is available as a single download — https://jamdesk.com/docs/api-specs.zip