Skip to content

Search (1.0.0)

Query your project's documentation and API reference content from external tools, scripts, or integrations (for example, MCP servers or custom search UIs).

Path prefix: If your project is deployed with a path prefix (for example, https://docs.example.com/docs/), prepend that prefix to the API paths (for example, /docs/_search).

For path prefix configuration, see custom domain configuration.

Authentication

This API uses the same authentication as the project. Public projects (when access.requiresLogin is not set or is false), don't require authentication when you call the API. If the project is protected, (access.requiresLogin: true or has RBAC configuration), you must send the same cookie-based session that the browser uses after users logs in.

The API does not support API keys or bearer tokens; authentication is session (cookie) only. For unauthenticated requests to protected projects, both endpoints return empty results instead of errors.

To learn more about access and authentication options, see Access control.

CORS and credentials

When calling from a browser (for example, a custom search UI on another origin), the project must allow your origin in CORS. Send credentials (cookies) with fetch(..., { credentials: 'include' }) so that session cookies are sent for protected projects.

Download OpenAPI description
openapi.json
openapi.yaml
Overview
License
Redocly
Terms of Service
Languages
Servers
Mock server
https://redocly.com/_mock/docs/realm/customization/search-api/openapi/
Project server
https://{projectUrl}/

Get search results

Request

Run a full-text search and get results grouped by category (for example, Documentation, API Reference).

Bodyapplication/jsonrequired
querystringrequired

Full-text search query.

localestringrequired

Locale code for the content to search (for example, en, default_locale). Must match a locale configured in your project. Locales are set in redocly.yaml under the l10n option.

filterArray of objects(FacetFilter)

List of facet filters. Omit or use [] for no filters.

loadMoreobject

For pagination within a result group.

curl -i -X POST \
  https://redocly.com/_mock/docs/realm/customization/search-api/openapi/_search \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "getting started",
    "filter": [],
    "locale": "default_locale"
  }'

Responses

Search results grouped by category.

Bodyapplication/json
facetsobject

Facet field names to arrays of value and count. Keys may include: redocly_category, redocly_product, redocly_version, redocly_teams, httpMethod, httpPath, apiTitle, apiVersion, and any custom facet fields.

documentsobject

Category names (e.g. Documentation, API Reference) to arrays of search items.

Response
application/json
{
  "facets": {
    "redocly_category": [ … ],
    "redocly_product": [],
    "redocly_version": [],
    "redocly_teams": [],
    "httpMethod": [],
    "httpPath": [],
    "apiTitle": [],
    "apiVersion": []
  },
  "documents": {
    "Documentation": [ … ]
  }
}

Get search facets

Request

Get facet definitions and counts for building filter UIs or refining search. Facet counts are optionally computed in the context of a search query and applied filters. Facet type can be: multi-select, select, tags, and so on, as configured in search filters.

Bodyapplication/jsonrequired
localestringrequired

Locale code (same as search).

fieldstring

If set, returns only the facet for this field (with values and counts). If omitted, returns all configured facets.

querystring

Search query; facet counts are computed in the context of this query.

filterArray of objects(FacetFilter)

Counts are computed with these filters applied.

facetQuerystring

Filter facet values using this string (for type-ahead in facet controls).

curl -i -X POST \
  https://redocly.com/_mock/docs/realm/customization/search-api/openapi/_search-facets \
  -H 'Content-Type: application/json' \
  -d '{
    "locale": "en"
  }'

Responses

Facet definitions with values and counts. If field is set in the request, returns an array with a single facet object; otherwise returns all configured facets.

Bodyapplication/jsonArray [
namestring

Display name of the facet as shown in the UI.

fieldstring

Facet field name (for example: redocly_category, redocly_product).

typestring

Facet type (for example: multi-select, select, tags) as configured in search filters.

valuesArray of objects(FacetValueCount)

Available facet values with their result counts.

]
Response
application/json
[
  {
    "name": "string",
    "field": "string",
    "type": "string",
    "values": [ … ]
  }
]