sitecore Querying API

openapi: 3.2.0
info:
  title: Sitecore Content Hub REST Querying 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. Developers use it to automate digital asset management workflows, migrate content, build custom integrations, and manage Content Hub configuration. The API supports standard CRUD operations and is authenticated using OAuth 2.0 tokens obtained from the Content Hub identity provider. Navigation between resources uses hyperlinks rather than hardcoded URL patterns. The base URL is tenant-specific and corresponds to the URL of the Content Hub instance followed by /api/.
  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: Querying
  description: Endpoints for fetching entities that match specific criteria using structured query expressions against entity properties and relations.
paths:
  /entities/query:
    post:
      operationId: queryEntities
      summary: Query entities
      description: Executes a structured query against the Content Hub entity index. Supports filtering by property values, relations, and entity definition using a query expression language. Returns matching entities with pagination.
      tags:
      - Querying
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntityQuery'
      responses:
        '200':
          description: Query results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityListResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    EntityListResponse:
      type: object
      description: A paginated list of entities
      properties:
        items:
          type: array
          description: The entities for the current page
          items:
            $ref: '#/components/schemas/Entity'
        totalCount:
          type: integer
          description: The total number of entities matching the query
        skip:
          type: integer
          description: The number of entities skipped
        take:
          type: integer
          description: The maximum number of entities returned
    EntityQuery:
      type: object
      description: A structured query for filtering entities
      properties:
        query:
          type: object
          description: The query expression object for filtering entities
          additionalProperties: true
        skip:
          type: integer
          description: Number of entities to skip
          default: 0
        take:
          type: integer
          description: Maximum number of entities to return
          default: 25
        cultures:
          type: array
          description: Culture codes for localized property values
          items:
            type: string
    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
    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
    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
  responses:
    Unauthorized:
      description: Authentication token is missing or invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: The request body or parameters are invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  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