openapi: 3.2.0
info:
  title: Search API
  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).
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).
      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.'
      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:
  responses:
    BadRequest:
      description: 'Facet field name (for example: `redocly_category`, `redocly_version`).

        '
      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
  schemas:
    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.

        '
    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`).

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

            '
        values:
          type: array
          description: Available facet values with their result counts.
          items:
            $ref: '#/components/schemas/FacetValueCount'
    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.

            '
        documents:
          type: object
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/SearchItem'
          description: Category names (e.g. Documentation, API Reference) to arrays of search items.
    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.

            '
          items:
            type: string
        redocly_category:
          type: string
          description: 'Documentation category (for example: Documentation, API Reference).

            '
        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.

            '
        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.
    FacetValueCount:
      type: object
      properties:
        value:
          type: string
          description: 'Facet value (for example: a category or product name).

            '
        count:
          type: integer
          description: Number of search results that match this facet value.
    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`).

            Must match a locale configured in your project. Locales are set in `redocly.yaml` under the [l10n](../../config/l10n.md) option.

            '
        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.
    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).

            '
        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'
    FacetFilter:
      type: object
      required:
      - field
      - values
      properties:
        field:
          type: string
          description: 'Facet field name (for example: `redocly_category`, `redocly_version`).

            '
        values:
          type: array
          items:
            type: string
          description: Selected facet values.