openapi: 3.1.0 info: title: Fumadocs Search API description: >- The Fumadocs Search API provides a server-side HTTP endpoint for querying documentation content indexed by Fumadocs Core. Documentation sites built with Fumadocs expose a GET endpoint (typically at /api/search) that accepts a search query and returns ranked, highlighted results including pages, headings, and text segments. Results can be filtered by tag and locale to scope searches within multilingual or multi-section documentation sites. The endpoint also supports a static export mode that returns the full search index for client-side search implementations. version: '16.6.17' contact: name: Fumadocs url: https://fumadocs.dev license: name: MIT url: https://github.com/fuma-nama/fumadocs/blob/main/LICENSE externalDocs: description: Fumadocs Search Documentation url: https://fumadocs.dev/docs/headless/search/orama servers: - url: '{baseUrl}' description: Fumadocs documentation site variables: baseUrl: default: http://localhost:3000 description: >- Base URL of the documentation site. Fumadocs is a self-hosted framework; each site sets its own base URL. tags: - name: Search description: >- Search endpoints for querying documentation content. Results include pages, headings, and text segments ranked by relevance. paths: /api/search: get: operationId: searchDocs summary: Fumadocs Search documentation content description: >- Searches indexed documentation content and returns a ranked list of matching pages, headings, and text segments. Accepts a query string and optional filters for locale and tag. Returns an empty array when no query is provided. Each result includes the page URL, content type, breadcrumbs, and highlighted content. The default endpoint path is /api/search but can be customized per site. tags: - Search parameters: - $ref: '#/components/parameters/query' - $ref: '#/components/parameters/locale' - $ref: '#/components/parameters/tag' - $ref: '#/components/parameters/limit' responses: '200': description: >- A list of search results ranked by relevance. Returns an empty array when the query parameter is absent. content: application/json: schema: type: array items: $ref: '#/components/schemas/SortedResult' '500': description: Server error during search execution. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /api/search/static: get: operationId: exportSearchIndex summary: Fumadocs Export the search index for static/client-side search description: >- Exports the full search index database so that client-side search implementations can download and query it locally without making per-query requests. The response format depends on the underlying search engine (Orama, Flexsearch, etc.) configured by the site. This endpoint path is a convention; actual path may vary per documentation site. tags: - Search responses: '200': description: >- The serialized search index. The structure depends on the configured search engine. content: application/json: schema: type: object description: >- Serialized search index. Schema is engine-dependent (Orama database export, Flexsearch export, etc.). additionalProperties: true '500': description: Server error during index export. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: parameters: query: name: query in: query required: false description: >- The search query string. When absent or empty, an empty results array is returned immediately without querying the index. schema: type: string example: 'getting started installation' locale: name: locale in: query required: false description: >- BCP 47 locale code to filter results to a specific language version of the documentation site. Useful for internationalized sites. schema: type: string example: 'en' tag: name: tag in: query required: false description: >- One or more comma-separated tag values to restrict search results to specific sections or categories within the documentation. Multiple tags are separated by commas. schema: type: string example: 'api,reference' limit: name: limit in: query required: false description: >- Maximum number of results to return. When omitted, the search engine's default limit is used. schema: type: integer minimum: 1 example: 10 schemas: SortedResult: type: object description: >- A single search result representing a matched page, heading, or text segment within the documentation. Results are pre-sorted by relevance score. required: - id - url - type - content properties: id: type: string description: >- Unique identifier for the result within the search index. Used for deduplication and client-side state management. example: 'docs/getting-started#installation' url: type: string description: >- Relative or absolute URL of the documentation page containing this result. May include a fragment identifier pointing to a specific heading. example: '/docs/getting-started#installation' type: type: string description: >- The granularity level of this search result. 'page' indicates the result refers to an entire page title match; 'heading' indicates a section heading match; 'text' indicates a body text segment match. enum: - page - heading - text content: type: string description: >- The matched text content for this result. May contain Markdown highlight markers (using elements) indicating the matched terms within the content. example: 'Getting **started** with Fumadocs **installation**' breadcrumbs: type: array description: >- Ordered list of ancestor page or section titles forming the navigation breadcrumb trail to this result. Displayed in the search UI to help users understand where the result is located. items: type: string example: - 'Docs' - 'Getting Started' ErrorResponse: type: object description: Error response returned when a server-side failure occurs. required: - message properties: message: type: string description: Human-readable description of the error. example: 'Internal server error during search.'