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