sitecore Search API

openapi: 3.2.0
info:
  title: Sitecore Content Hub REST Search API
  description: The Sitecore Content Hub REST API is a hypermedia API built on HTTP that provides programmatic access to the full range of Content Hub resources, including entities, assets, jobs, search, selections, upload, and audit logs.
  version: v1
  contact:
    name: Sitecore Support
    url: https://www.sitecore.com/support
  termsOfService: https://www.sitecore.com/legal/terms-of-service
servers:
- url: https://{tenant}.stylelabs.io/api
  description: Content Hub Production Server
  variables:
    tenant:
      description: The tenant-specific subdomain for the Content Hub instance
      default: your-tenant
security:
- bearerAuth: []
tags:
- name: Search
  description: Endpoints for executing search queries against the Content Hub entity index, retrieving facet values, and managing search filters.
paths:
  /search:
    post:
      operationId: searchEntities
      summary: Search entities
      description: Executes a full-text and structured search query across the Content Hub entity index. Returns matching entities with facet aggregations for interactive filtering. Supports relevance ranking and pagination.
      tags:
      - Search
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
      responses:
        '200':
          description: Search results with facets
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  responses:
    BadRequest:
      description: The request body or parameters are invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Authentication token is missing or invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    SystemProperties:
      type: object
      description: System-managed metadata properties on a Content Hub entity
      properties:
        createdOn:
          type: string
          description: The ISO 8601 timestamp when the entity was created
          format: date-time
        createdBy:
          type: string
          description: The username of the user who created the entity
        modifiedOn:
          type: string
          description: The ISO 8601 timestamp when the entity was last modified
          format: date-time
        modifiedBy:
          type: string
          description: The username of the user who last modified the entity
    SearchResponse:
      type: object
      description: Search results with facet aggregations
      properties:
        items:
          type: array
          description: Matching entities for the current page
          items:
            $ref: '#/components/schemas/Entity'
        totalCount:
          type: integer
          description: Total number of matching entities
        facets:
          type: object
          description: Facet aggregations keyed by facet field name
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/FacetValue'
    ErrorResponse:
      type: object
      description: An error response body
      properties:
        message:
          type: string
          description: A human-readable error message
        statusCode:
          type: integer
          description: The HTTP status code
        errors:
          type: array
          description: List of detailed error messages
          items:
            type: string
    Entity:
      type: object
      description: A Content Hub entity representing any resource such as an asset or taxonomy node
      properties:
        id:
          type: integer
          description: The numeric identifier of the entity
        identifier:
          type: string
          description: The human-readable string identifier of the entity
        definitionName:
          type: string
          description: The name of the entity definition this entity conforms to
        cultures:
          type: array
          description: Culture codes for which the entity has localized data
          items:
            type: string
        properties:
          type: object
          description: Key-value map of entity property names to their values
          additionalProperties: true
        relations:
          type: object
          description: Key-value map of relation names to related entity references
          additionalProperties: true
        systemProperties:
          $ref: '#/components/schemas/SystemProperties'
        links:
          type: object
          description: Hypermedia links for navigating to related resources
          additionalProperties:
            type: string
            format: uri
    SearchRequest:
      type: object
      description: A search request for querying entities with faceting
      properties:
        query:
          type: string
          description: Full-text search query string
        filters:
          type: array
          description: Structured filters to apply to the search
          items:
            type: object
            additionalProperties: true
        skip:
          type: integer
          description: Number of results to skip
          default: 0
        take:
          type: integer
          description: Maximum number of results to return
          default: 25
        facets:
          type: array
          description: Facet field names to include in the response
          items:
            type: string
    FacetValue:
      type: object
      description: A single facet value with its count in search results
      properties:
        value:
          type: string
          description: The facet value
        count:
          type: integer
          description: The number of matching entities with this value
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OAuth 2.0 bearer token obtained from the Content Hub identity provider. Include the token in the Authorization header as 'Bearer {token}'.
externalDocs:
  description: Sitecore Content Hub REST API Documentation
  url: https://doc.sitecore.com/ch/en/developers/cloud-dev/rest-apis.html