> ## Documentation Index
> Fetch the complete documentation index at: https://help.experro.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Categories

> Returns catalog categories matching a text query, typically used to power a category autocomplete or typeahead UI.

Categories configured as autocomplete exclusions in the catalog's search settings are automatically excluded.

Before calling this endpoint, make sure you've generated an API token and picked the correct domain. See [Authentication & Base URLs](/api-reference/authbaseurl).

Use this to power a category typeahead. For term suggestions, use [Auto-Suggestions](/api-reference/discovery/auto-suggestions/get); for the product search itself, use [Search Products](/api-reference/discovery/search/post).


## OpenAPI

````yaml GET /discovery/search/categories
openapi: 3.1.0
info:
  title: OpenAPI Plant Store
  description: >-
    A sample API that uses a plant store as an example to demonstrate features
    in the OpenAPI specification
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://apis.experro.app
    description: Admin Server
  - url: https://{base-address}
    description: Custom Server
    variables:
      base-address:
        default: ''
        description: Enter your custom domain or server address.
security:
  - bearerAuth: []
paths:
  /discovery/search/categories:
    get:
      summary: Search / Autocomplete Categories
      description: >-
        Returns catalog categories matching a text query, typically used to
        power a category autocomplete or typeahead UI.


        Categories configured as autocomplete exclusions in the catalog's search
        settings are automatically excluded.
      parameters:
        - $ref: '#/components/parameters/StorefrontTenantIdHeader'
        - $ref: '#/components/parameters/StorefrontWorkspaceIdHeader'
        - $ref: '#/components/parameters/StorefrontEnvironmentIdHeader'
        - name: catalog_id
          in: query
          description: Catalog to search categories within.
          required: true
          schema:
            type: string
            format: uuid
        - name: q
          in: query
          description: Text query to match categories against.
          required: true
          schema:
            type: string
        - name: locale
          in: query
          description: Locale for the category names.
          schema:
            type: string
        - name: limit
          in: query
          description: Maximum number of categories to return.
          schema:
            type: integer
            default: 10
        - name: skip
          in: query
          description: Number of categories to skip.
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CategorySearchResult'
        '400':
          description: >-
            The request could not be parsed or validated. `Invalid Input` almost
            always means a request-body problem rather than a bad field value:


            - The `Content-Type` is missing or is not `application/json`.

            - The body was sent as form data instead of raw JSON.

            - The body is empty, or is not valid JSON.

            - An optional field was sent **blank rather than omitted** — for
            example `"sort_order": ""`, `"hero_variant_option_override": {}`, or
            `"filters": [{}]`. Omit a field you are not using, or send `null` or
            `[]`; an empty string or empty object is rejected.

            - A numeric field was sent as a string, such as `"limit": "24"`
            instead of `"limit": 24`.


            A missing required query parameter returns a more specific message,
            for example `Query deserialize error: missing field \`catalog_id\``.
        '404':
          description: The catalog was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
      security: []
      servers:
        - url: https://{base-address}
          description: Custom Server
          variables:
            base-address:
              default: ''
              description: Enter your custom domain or server address.
components:
  parameters:
    StorefrontTenantIdHeader:
      name: x-tenant-id
      in: header
      required: true
      schema:
        type: string
      description: Identifies your organization. Ensures data isolation per tenant.
    StorefrontWorkspaceIdHeader:
      name: x-workspace-id
      in: header
      required: true
      schema:
        type: string
      description: >-
        Identifies the workspace within your organization. Scopes resources to a
        specific workspace.
    StorefrontEnvironmentIdHeader:
      name: x-environment-id
      in: header
      required: true
      schema:
        type: string
      description: >-
        Identifies the environment you are targeting. Scopes the call to a
        specific deployment environment.
  schemas:
    CategorySearchResult:
      type: object
      description: Catalog categories matching the query.
      properties:
        categories:
          type: array
          description: >-
            Matching categories, ordered by relevance. Empty when nothing
            matches.
          items:
            $ref: '#/components/schemas/CategorySuggestion'
        total_count:
          type: integer
          description: >-
            Total number of matching categories, before `limit` and `skip` are
            applied.
      additionalProperties: false
    Error404:
      type: object
      properties:
        Status:
          type: string
          example: failure
        Error:
          type: object
          properties:
            message:
              type: string
            name:
              type: string
            code:
              type: string
          required:
            - message
            - name
      required:
        - Status
        - Error
    Error500:
      type: object
      properties:
        Status:
          type: string
          example: failure
        Error:
          type: object
          properties:
            message:
              type: string
            name:
              type: string
            code:
              type: string
          required:
            - message
            - name
      required:
        - Status
        - Error
    CategorySuggestion:
      type: object
      description: One matching category.
      properties:
        id:
          type: string
          description: Experro category id.
        name:
          type: string
          description: Category name.
        provider_id:
          type: string
          description: Category id in the source commerce platform.
        url:
          type: string
          description: >-
            Category URL, relative to your storefront. Present only on catalogs
            where category URLs are configured.
      additionalProperties: false
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````