{
  "openapi": "3.1.0",
  "info": {
    "title": "Search",
    "version": "1.0.0",
    "termsOfService": "https://redocly.com/subscription-agreement",
    "license": {
      "name": "Redocly",
      "url": "https://redocly.com/subscription-agreement"
    },
    "description": "Query your project's documentation and API reference content from external tools, scripts, or integrations (for example, MCP servers or custom search UIs).\n\n**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`).\n\n{% admonition type=\"info\" %}\nFor path prefix configuration, see [custom domain configuration](../../reunite/project/custom-domain.md#serve-from-a-subdirectory).\n{% /admonition %}\n\n## Authentication\n\nThis 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. \nIf the project is protected, (`access.requiresLogin: true` or has [RBAC](../../access/rbac.md) configuration), you must send the same cookie-based session that the browser uses after users logs in. \n\nThe 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.\n{% admonition type=\"info\" %}\nTo learn more about access and authentication options, see [Access control](../../access/index.md).\n{% /admonition %}\n\n## CORS and credentials\n\nWhen 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.\n"
  },
  "servers": [
    {
      "url": "https://{projectUrl}",
      "description": "Project server",
      "variables": {
        "projectUrl": {
          "default": "redocly.com",
          "description": "Project URL (prepend your path prefix if applicable)."
        }
      }
    }
  ],
  "security": [],
  "tags": [
    {
      "name": "Search",
      "description": "Full-text search and facet operations."
    }
  ],
  "paths": {
    "/_search": {
      "post": {
        "tags": [
          "Search"
        ],
        "summary": "Get search results",
        "description": "Run a full-text search and get results grouped by category (for example, Documentation, API Reference).\n",
        "operationId": "search",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SearchRequest"
              },
              "example": {
                "query": "getting started",
                "filter": [],
                "locale": "default_locale"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Search results grouped by category.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                },
                "example": {
                  "facets": {
                    "redocly_category": [
                      {
                        "value": "Documentation",
                        "count": 2
                      },
                      {
                        "value": "API Reference",
                        "count": 0
                      }
                    ],
                    "redocly_product": [],
                    "redocly_version": [],
                    "redocly_teams": [],
                    "httpMethod": [],
                    "httpPath": [],
                    "apiTitle": [],
                    "apiVersion": []
                  },
                  "documents": {
                    "Documentation": [
                      {
                        "document": {
                          "id": "doc-1",
                          "url": "/guides/getting-started",
                          "title": "Getting started",
                          "text": "This guide walks you through the initial setup.",
                          "path": [],
                          "redocly_category": "Documentation",
                          "redocly_product": "",
                          "redocly_teams": [],
                          "redocly_version": {
                            "isDefault": true
                          }
                        },
                        "highlight": {
                          "id": "doc-1",
                          "title": "Getting started",
                          "url": "/guides/getting-started",
                          "text": "This guide walks you through the <mark>getting</mark> <mark>started</mark> setup.",
                          "redocly_category": "Documentation",
                          "redocly_product": "",
                          "parameters": []
                        }
                      }
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          }
        }
      }
    },
    "/_search-facets": {
      "post": {
        "operationId": "searchFacets",
        "tags": [
          "Search"
        ],
        "summary": "Get search facets",
        "description": "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.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SearchFacetsRequest"
              },
              "examples": {
                "allFacets": {
                  "summary": "All facets",
                  "value": {
                    "locale": "en"
                  }
                },
                "singleFacetWithQuery": {
                  "summary": "One facet with query and filter",
                  "value": {
                    "locale": "en",
                    "field": "redocly_category",
                    "query": "api",
                    "filter": [
                      {
                        "field": "redocly_version",
                        "values": [
                          "v1"
                        ]
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "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.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchFacetsResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "FacetFilter": {
        "type": "object",
        "required": [
          "field",
          "values"
        ],
        "properties": {
          "field": {
            "type": "string",
            "description": "Facet field name (for example: `redocly_category`, `redocly_version`).\n"
          },
          "values": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Selected facet values."
          }
        }
      },
      "SearchRequest": {
        "type": "object",
        "required": [
          "query",
          "locale"
        ],
        "properties": {
          "query": {
            "type": "string",
            "description": "Full-text search query."
          },
          "locale": {
            "type": "string",
            "description": "Locale code for the content to search (for example, `en`, `default_locale`).\nMust match a locale configured in your project. Locales are set in `redocly.yaml` under the [l10n](https://redocly.com/docs/realm/config/l10n) option.\n"
          },
          "filter": {
            "type": "array",
            "description": "List of facet filters. Omit or use [] for no filters.",
            "items": {
              "$ref": "#/components/schemas/FacetFilter"
            }
          },
          "loadMore": {
            "type": "object",
            "description": "For pagination within a result group.",
            "properties": {
              "groupKey": {
                "type": "string",
                "description": "Category key to load more results for."
              },
              "offset": {
                "type": "integer",
                "description": "Offset for pagination within the group."
              }
            }
          }
        }
      },
      "FacetValueCount": {
        "type": "object",
        "properties": {
          "value": {
            "type": "string",
            "description": "Facet value (for example: a category or product name).\n"
          },
          "count": {
            "type": "integer",
            "description": "Number of search results that match this facet value."
          }
        }
      },
      "SearchDocument": {
        "description": "Indexed document returned in search results.",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier of the indexed document."
          },
          "url": {
            "type": "string",
            "description": "URL of the document or API operation."
          },
          "title": {
            "type": "string",
            "description": "Document or page title."
          },
          "text": {
            "type": "string",
            "description": "Indexed text content used for search matching."
          },
          "path": {
            "type": "array",
            "description": "Breadcrumb path (for example: section titles) leading to this document.\n",
            "items": {
              "type": "string"
            }
          },
          "redocly_category": {
            "type": "string",
            "description": "Documentation category (for example: Documentation, API Reference).\n"
          },
          "redocly_product": {
            "type": "string",
            "description": "Product name when content is scoped by product."
          },
          "redocly_teams": {
            "type": "array",
            "description": "Team names when content is scoped by team.",
            "items": {
              "type": "string"
            }
          },
          "redocly_version": {
            "oneOf": [
              {
                "type": "object",
                "properties": {
                  "isDefault": {
                    "type": "boolean",
                    "description": "Whether this is the default version."
                  }
                }
              },
              {
                "type": "string"
              }
            ],
            "description": "Version label or version object for versioned content."
          },
          "httpMethod": {
            "type": "string",
            "description": "HTTP method (for example: GET, POST) for API reference items.\n"
          },
          "httpPath": {
            "type": "string",
            "description": "HTTP path pattern for API reference items."
          },
          "apiTitle": {
            "type": "string",
            "description": "Title of the API for API reference items."
          },
          "apiVersion": {
            "type": "string",
            "description": "API version for API reference items."
          }
        }
      },
      "SearchHighlight": {
        "description": "Highlighted snippets; matched terms are wrapped in `<mark>` tags.",
        "properties": {
          "id": {
            "type": "string",
            "description": "Document ID matching the result document."
          },
          "title": {
            "type": "string",
            "description": "Highlighted title snippet with matched terms in `<mark>` tags."
          },
          "url": {
            "type": "string",
            "description": "URL of the result (no highlighting)."
          },
          "text": {
            "type": "string",
            "description": "Highlighted content snippet with matched terms in `<mark>` tags."
          },
          "redocly_category": {
            "type": "string",
            "description": "Category value for this result (for example: Documentation, API Reference).\n"
          },
          "redocly_product": {
            "type": "string",
            "description": "Product value for this result when applicable."
          },
          "parameters": {
            "type": "array",
            "description": "Present in API reference items."
          }
        }
      },
      "SearchItem": {
        "type": "object",
        "properties": {
          "document": {
            "type": "object",
            "description": "The indexed document (metadata and content fields).",
            "$ref": "#/components/schemas/SearchDocument"
          },
          "highlight": {
            "type": "object",
            "description": "Highlighted snippets for this result.",
            "$ref": "#/components/schemas/SearchHighlight"
          }
        }
      },
      "SearchResponse": {
        "type": "object",
        "properties": {
          "facets": {
            "type": "object",
            "additionalProperties": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/FacetValueCount"
              }
            },
            "description": "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.\n"
          },
          "documents": {
            "type": "object",
            "additionalProperties": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/SearchItem"
              }
            },
            "description": "Category names (e.g. Documentation, API Reference) to arrays of search items."
          }
        }
      },
      "SearchFacetsRequest": {
        "type": "object",
        "required": [
          "locale"
        ],
        "properties": {
          "locale": {
            "type": "string",
            "description": "Locale code (same as search)."
          },
          "field": {
            "type": "string",
            "description": "If set, returns only the facet for this field (with values and counts). If omitted, returns all configured facets."
          },
          "query": {
            "type": "string",
            "description": "Search query; facet counts are computed in the context of this query."
          },
          "filter": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FacetFilter"
            },
            "description": "Counts are computed with these filters applied."
          },
          "facetQuery": {
            "type": "string",
            "description": "Filter facet values using this string (for type-ahead in facet controls)."
          }
        }
      },
      "FacetObject": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Display name of the facet as shown in the UI."
          },
          "field": {
            "type": "string",
            "description": "Facet field name (for example: `redocly_category`, `redocly_product`).\n"
          },
          "type": {
            "type": "string",
            "description": "Facet type (for example: multi-select, select, tags) as configured in search filters.\n"
          },
          "values": {
            "type": "array",
            "description": "Available facet values with their result counts.",
            "items": {
              "$ref": "#/components/schemas/FacetValueCount"
            }
          }
        }
      },
      "SearchFacetsResponse": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/FacetObject"
        },
        "description": "If the request includes `field`: array with a single facet. Otherwise all facet objects with their values.\n"
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Facet field name (for example: `redocly_category`, `redocly_version`).\n",
        "content": {
          "application/problem+json": {
            "schema": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string",
                  "description": "URI reference that identifies the problem type.",
                  "example": "about:blank"
                },
                "title": {
                  "type": "string",
                  "description": "Error title.",
                  "example": "Bad Request"
                },
                "status": {
                  "type": "integer",
                  "description": "HTTP status code.",
                  "example": 400
                },
                "detail": {
                  "type": "string",
                  "description": "Human-readable message with additional error details.",
                  "example": "Invalid or missing required body fields."
                }
              },
              "required": [
                "detail"
              ]
            }
          }
        }
      }
    }
  }
}