openapi: 3.0.1
info:
  title: Querying API
  description: >
    Use the Querying API to fetch multiple pages of search results sequentially.
    This REST API lets you to retrieve entities that match a specific criteria.

     ## Authentication

     To use the Querying API, you need:

      - The URL of your Content Hub server. You can get this from your Content Hub Administrator. Enter this URL in the <b>{{server}}</b> variable by hovering over the variable in the <b>Try it</b> pane and then clicking <b>Edit</b>.
      - An [access token and the client ID](https://doc.sitecore.com/ch/en/developers/cloud-dev/oauth-tokens.html#making-requests). Both are sent with every request. You can create a token through the [Content Hub interface](https://doc.sitecore.com/ch/en/users/content-hub/create-an-oauth-client.html)  or by [requesting one to the API itself](https://doc.sitecore.com/ch/en/developers/cloud-dev/oauth-tokens.html#grant-flows)
  version: v2.0
  x-metadata:
    product: Content Hub
  license:
    name: closed source
    url: https://www.sitecore.com
servers:
  - url: https://{server}
    variables:
      server:
        default: your-server
security:
  - oauth2: []
tags:
  - name: Querying
    description: >-
      The Querying API is responsible for fetching multiple pages of results
      sequentially.
paths:
  /api/entities/searchAfter:
    post:
      tags:
        - Querying
      summary: Retrieve a list of entities based on a search query
      description: >-
        Lists all entities that match the criteria. This endpoint supports
        sorted pagination using the `search_after` parameter.
      operationId: EntitiesBySearchAfterV2
      requestBody:
        description: Request for executing queries with pagination.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchAfterRequest'
        required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityCollectionResource'
        '400':
          description: Request not valid
        '401':
          description: Unauthorized request or invalid access token
      security:
        - oauth2: []
components:
  schemas:
    AncestorIdQueryNodeFilter:
      allOf:
        - $ref: '#/components/schemas/QueryNodeFilter'
        - required:
            - id
            - relation
          type: object
          properties:
            relation:
              minLength: 1
              type: string
              description: Gets or sets ancestor relation name.
            id:
              type: integer
              description: Gets or sets ancestor ID.
              format: int64
            type:
              $ref: '#/components/schemas/QueryNodeFilterType'
          additionalProperties: false
      description: A query for entities using an ancestor filter.
    CreatedByQueryNodeFilter:
      allOf:
        - $ref: '#/components/schemas/QueryNodeFilter'
        - required:
            - user_id
          type: object
          properties:
            user_id:
              type: integer
              description: Gets or sets the user id.
              format: int64
            type:
              $ref: '#/components/schemas/QueryNodeFilterType'
          additionalProperties: false
      description: A query for entities using a specified user filter.
    CultureLoadOption:
      type: object
      properties:
        load_option:
          $ref: '#/components/schemas/LoadOption'
        cultures:
          type: array
          items:
            type: string
          description: "Gets or sets a list of cultures names that need to be loaded.\r\nThis is only useful when Stylelabs.M.Base.Entities.Loading.CultureLoadOption.LoadOption is Stylelabs.M.Base.Entities.Loading.LoadOption.Custom."
          nullable: true
      additionalProperties: false
      description: Represents options for loading cultures.
    DefinitionIdQueryNodeFilter:
      allOf:
        - $ref: '#/components/schemas/QueryNodeFilter'
        - required:
            - id
          type: object
          properties:
            id:
              type: integer
              description: Gets or sets the definition id.
              format: int64
            type:
              $ref: '#/components/schemas/QueryNodeFilterType'
          additionalProperties: false
      description: A query for entities using a specified defintion filter.
    DefinitionNameQueryNodeFilter:
      allOf:
        - $ref: '#/components/schemas/QueryNodeFilter'
        - required:
            - name
          type: object
          properties:
            name:
              minLength: 1
              type: string
              description: gets or sets the definition name.
            type:
              $ref: '#/components/schemas/QueryNodeFilterType'
          additionalProperties: false
      description: A query for entities using a specified definition filter.
    EntityCollectionResource:
      type: object
      properties:
        last_hit_data:
          type: array
          items:
            type: string
          description: >-
            The last returned results, which are used to fetch the next page of
            results.
          nullable: true
        items:
          type: array
          items:
            $ref: '#/components/schemas/EntityResource'
          description: Gets or sets the list of items.
          nullable: true
        total_items:
          type: integer
          description: Gets or sets the total number of items.
          format: int64
          nullable: true
        returned_items:
          type: integer
          description: Gets or sets the number of returned items.
          format: int64
          nullable: true
        offset:
          type: integer
          description: Gets or sets the offset of the items.
          format: int32
          nullable: true
        next:
          $ref: '#/components/schemas/Link'
        previous:
          $ref: '#/components/schemas/Link'
        identifier:
          type: string
          description: Gets or sets the identifier of the resource.
          nullable: true
        self:
          $ref: '#/components/schemas/Link'
      additionalProperties: {}
      description: Collection of entities resulted of a query
    EntityLoadConfiguration:
      type: object
      properties:
        culture_option:
          $ref: '#/components/schemas/CultureLoadOption'
        property_option:
          $ref: '#/components/schemas/PropertyLoadOption'
        relation_option:
          $ref: '#/components/schemas/RelationLoadOption'
      additionalProperties: false
      description: Represents the configuration for loading an entity.
    EntityResource:
      type: object
      properties:
        id:
          type: integer
          description: The ID for the entity, for example `39752`.
          format: int64
        identifier:
          type: string
          description: The identifier for the entity.
          nullable: true
        cultures:
          type: array
          items:
            type: string
          description: The cultures associated with the entity, for example `en-US`.
          nullable: true
        properties:
          type: object
          additionalProperties:
            type: object
            nullable: true
          description: The properties of the entity.
          nullable: true
        relations:
          type: object
          additionalProperties:
            type: object
            nullable: true
          description: The relations of the entity.
          nullable: true
        created_by:
          $ref: '#/components/schemas/Link'
        created_on:
          type: string
          description: The date and time when the entity was created.
          format: date-time
        modified_by:
          $ref: '#/components/schemas/Link'
        modified_on:
          type: string
          description: The date and time when the entity was last modified.
          format: date-time
        locked_by:
          $ref: '#/components/schemas/Link'
        locked_on:
          type: string
          description: The date and time when the entity was locked.
          format: date-time
          nullable: true
        entitydefinition:
          $ref: '#/components/schemas/Link'
        copy:
          $ref: '#/components/schemas/Link'
        copyasync:
          $ref: '#/components/schemas/Link'
        permissions:
          $ref: '#/components/schemas/Link'
        requested_permissions:
          type: object
          additionalProperties:
            type: boolean
            nullable: true
          description: >-
            The requested permissions with identification if a certain user has
            the permission.
          nullable: true
        lifecycle:
          $ref: '#/components/schemas/Link'
        saved_selections:
          $ref: '#/components/schemas/Link'
        roles:
          $ref: '#/components/schemas/Link'
        annotations:
          $ref: '#/components/schemas/Link'
        is_root_taxonomy_item:
          type: boolean
          description: >-
            Gets or sets a value indicating whether the entity is a root
            taxonomy item.
          nullable: true
        is_path_root:
          type: boolean
          description: Gets or sets a value indicating whether the entity is a path root.
          nullable: true
        inherits_security:
          type: boolean
          description: >-
            Gets or sets a value indicating whether the entity inherits
            security.
        is_system_owned:
          type: boolean
          description: Gets or sets a value indicating whether the entity is system owned.
        version:
          type: integer
          description: The version of the entity.
          format: int64
        full:
          $ref: '#/components/schemas/Link'
        modules:
          type: array
          items:
            type: string
          description: The modules associated with the entity.
          nullable: true
        self:
          $ref: '#/components/schemas/Link'
      additionalProperties: {}
      description: >-
        Represents an entity resource with various properties, relations and
        metadata.
    FilterOperator:
      enum:
        - None
        - Equals
        - LessThan
        - GreaterThan
        - Between
        - StartsWith
        - EndsWith
        - Contains
        - FacetEquals
        - DoesNotContain
        - DoesNotStartWith
        - DoesNotEndWith
        - LessThanOrEquals
        - GreaterThanOrEquals
        - DoesNotEqual
        - AnyOf
        - AllOf
        - NoneOf
        - Missing
        - Exists
        - Changed
      type: string
    FullTextQueryNodeFilter:
      allOf:
        - $ref: '#/components/schemas/QueryNodeFilter'
        - required:
            - value
          type: object
          properties:
            value:
              minLength: 1
              type: string
              description: Gets or sets the text value.
            type:
              $ref: '#/components/schemas/QueryNodeFilterType'
          additionalProperties: false
      description: A query for entities using a specified full text filter.
    IdInQueryNodeFilter:
      allOf:
        - $ref: '#/components/schemas/QueryNodeFilter'
        - required:
            - ids
          type: object
          properties:
            ids:
              type: array
              items:
                type: integer
                format: int64
              description: gets or sets the ids.
            type:
              $ref: '#/components/schemas/QueryNodeFilterType'
          additionalProperties: false
      description: A query for entities using a specified ids filter.
    IdentifierQueryNodeFilter:
      allOf:
        - $ref: '#/components/schemas/QueryNodeFilter'
        - required:
            - identifier
          type: object
          properties:
            identifier:
              minLength: 1
              type: string
              description: gets or sets the identifier.
            type:
              $ref: '#/components/schemas/QueryNodeFilterType'
          additionalProperties: false
      description: A query for entities using a specified identifier filter.
    Link:
      type: object
      properties:
        href:
          type: string
          description: >-
            Gets or sets the URI that points to the resource this link refers
            to.
          nullable: true
        filename_properties:
          type: array
          items:
            type: string
          description: >-
            Gets or sets the URI that points to the resource this link refers
            to.
          nullable: true
        title:
          type: string
          description: Gets or sets the title that describes this link.
          nullable: true
        templated:
          type: boolean
          description: >-
            Gets or sets a value indicating whether the contained URI is a
            template.
          default: false
      additionalProperties: false
      description: Represents a link to a resource.
    LoadOption:
      enum:
        - None
        - Default
        - Custom
        - All
      type: string
      description: An enum of possible load options.
    LockedByQueryNodeFilter:
      allOf:
        - $ref: '#/components/schemas/QueryNodeFilter'
        - required:
            - user_id
          type: object
          properties:
            user_id:
              type: integer
              description: gets or sets the user id.
              format: int64
            type:
              $ref: '#/components/schemas/QueryNodeFilterType'
          additionalProperties: false
      description: A query for entities using a specified user filter.
    LockedQueryNodeFilter:
      allOf:
        - $ref: '#/components/schemas/QueryNodeFilter'
        - type: object
          properties:
            type:
              $ref: '#/components/schemas/QueryNodeFilterType'
          additionalProperties: false
      description: A query filter for entities that are locked.
    LogicalOperator:
      enum:
        - And
        - Or
        - AndNot
      type: string
    LogicalQueryNodeFilter:
      allOf:
        - $ref: '#/components/schemas/QueryNodeFilter'
        - required:
            - left
            - operator
            - right
          type: object
          properties:
            left:
              oneOf:
                - $ref: '#/components/schemas/AncestorIdQueryNodeFilter'
                - $ref: '#/components/schemas/CreatedByQueryNodeFilter'
                - $ref: '#/components/schemas/DefinitionIdQueryNodeFilter'
                - $ref: '#/components/schemas/DefinitionNameQueryNodeFilter'
                - $ref: '#/components/schemas/FullTextQueryNodeFilter'
                - $ref: '#/components/schemas/IdentifierQueryNodeFilter'
                - $ref: '#/components/schemas/IdInQueryNodeFilter'
                - $ref: '#/components/schemas/LockedByQueryNodeFilter'
                - $ref: '#/components/schemas/LockedQueryNodeFilter'
                - $ref: '#/components/schemas/LogicalQueryNodeFilter'
                - $ref: '#/components/schemas/ModifiedByQueryNodeFilter'
                - $ref: '#/components/schemas/NegatingQueryNodeFilter'
                - $ref: '#/components/schemas/PathRootQueryNodeFilter'
                - $ref: '#/components/schemas/ObjectPropertyQueryNodeFilter'
                - $ref: '#/components/schemas/RelationExistsQueryNodeFilter'
                - $ref: '#/components/schemas/RelationQueryNodeFilter'
                - $ref: '#/components/schemas/RootTaxonomyItemQueryNodeFilter'
                - $ref: '#/components/schemas/SelectionQueryNodeFilter'
              description: Gets or sets the left operant.
            right:
              oneOf:
                - $ref: '#/components/schemas/AncestorIdQueryNodeFilter'
                - $ref: '#/components/schemas/CreatedByQueryNodeFilter'
                - $ref: '#/components/schemas/DefinitionIdQueryNodeFilter'
                - $ref: '#/components/schemas/DefinitionNameQueryNodeFilter'
                - $ref: '#/components/schemas/FullTextQueryNodeFilter'
                - $ref: '#/components/schemas/IdentifierQueryNodeFilter'
                - $ref: '#/components/schemas/IdInQueryNodeFilter'
                - $ref: '#/components/schemas/LockedByQueryNodeFilter'
                - $ref: '#/components/schemas/LockedQueryNodeFilter'
                - $ref: '#/components/schemas/LogicalQueryNodeFilter'
                - $ref: '#/components/schemas/ModifiedByQueryNodeFilter'
                - $ref: '#/components/schemas/NegatingQueryNodeFilter'
                - $ref: '#/components/schemas/PathRootQueryNodeFilter'
                - $ref: '#/components/schemas/ObjectPropertyQueryNodeFilter'
                - $ref: '#/components/schemas/RelationExistsQueryNodeFilter'
                - $ref: '#/components/schemas/RelationQueryNodeFilter'
                - $ref: '#/components/schemas/RootTaxonomyItemQueryNodeFilter'
                - $ref: '#/components/schemas/SelectionQueryNodeFilter'
              description: Gets or sets the right operant.
            operator:
              $ref: '#/components/schemas/LogicalOperator'
            type:
              $ref: '#/components/schemas/QueryNodeFilterType'
          additionalProperties: false
      description: A logical query filter.
    ModifiedByQueryNodeFilter:
      allOf:
        - $ref: '#/components/schemas/QueryNodeFilter'
        - required:
            - user_id
          type: object
          properties:
            user_id:
              type: integer
              description: Gets or sets the user id.
              format: int64
            type:
              $ref: '#/components/schemas/QueryNodeFilterType'
          additionalProperties: false
      description: A query for entities using a specified user filter.
    NegatingQueryNodeFilter:
      allOf:
        - $ref: '#/components/schemas/QueryNodeFilter'
        - required:
            - query
          type: object
          properties:
            query:
              oneOf:
                - $ref: '#/components/schemas/AncestorIdQueryNodeFilter'
                - $ref: '#/components/schemas/CreatedByQueryNodeFilter'
                - $ref: '#/components/schemas/DefinitionIdQueryNodeFilter'
                - $ref: '#/components/schemas/DefinitionNameQueryNodeFilter'
                - $ref: '#/components/schemas/FullTextQueryNodeFilter'
                - $ref: '#/components/schemas/IdentifierQueryNodeFilter'
                - $ref: '#/components/schemas/IdInQueryNodeFilter'
                - $ref: '#/components/schemas/LockedByQueryNodeFilter'
                - $ref: '#/components/schemas/LockedQueryNodeFilter'
                - $ref: '#/components/schemas/LogicalQueryNodeFilter'
                - $ref: '#/components/schemas/ModifiedByQueryNodeFilter'
                - $ref: '#/components/schemas/NegatingQueryNodeFilter'
                - $ref: '#/components/schemas/PathRootQueryNodeFilter'
                - $ref: '#/components/schemas/ObjectPropertyQueryNodeFilter'
                - $ref: '#/components/schemas/RelationExistsQueryNodeFilter'
                - $ref: '#/components/schemas/RelationQueryNodeFilter'
                - $ref: '#/components/schemas/RootTaxonomyItemQueryNodeFilter'
                - $ref: '#/components/schemas/SelectionQueryNodeFilter'
              description: Gets or sets the query to negate.
            type:
              $ref: '#/components/schemas/QueryNodeFilterType'
          additionalProperties: false
      description: A negating query filter.
    ObjectPropertyQueryNodeFilter:
      allOf:
        - $ref: '#/components/schemas/QueryNodeFilter'
        - required:
            - operator
            - property_name
            - value
          type: object
          properties:
            property_name:
              minLength: 1
              type: string
              description: Gets or sets the property name.
            culture:
              type: string
              description: Gets or sets the culture.
              nullable: true
            value:
              description: Gets or sets the value.
            operator:
              $ref: '#/components/schemas/FilterOperator'
            type:
              $ref: '#/components/schemas/QueryNodeFilterType'
          additionalProperties: false
      description: Base property query filter.
    PathRootQueryNodeFilter:
      allOf:
        - $ref: '#/components/schemas/QueryNodeFilter'
        - type: object
          properties:
            type:
              $ref: '#/components/schemas/QueryNodeFilterType'
          additionalProperties: false
      description: A query filter for entities that are path root.
    PropertyLoadOption:
      type: object
      properties:
        load_option:
          $ref: '#/components/schemas/LoadOption'
        properties:
          type: array
          items:
            type: string
          description: "Gets or sets a list of property names (case insensitive) that need to be loaded.\r\nThis is only useful when Stylelabs.M.Base.Entities.Loading.PropertyLoadOption.LoadOption is Stylelabs.M.Base.Entities.Loading.LoadOption.Custom."
          nullable: true
      additionalProperties: false
      description: Represents options for loading properties.
    QueryNodeFilter:
      required:
        - type
      type: object
      properties:
        type:
          $ref: '#/components/schemas/QueryNodeFilterType'
      additionalProperties: false
      description: Base query filter for entities.
    QueryNodeFilterType:
      enum:
        - Negating
        - Logical
        - DefinitionId
        - DefinitionName
        - RootTaxonomyItem
        - PathRoot
        - Locked
        - LockedBy
        - CreatedBy
        - ModifiedBy
        - FullText
        - Identifier
        - IdIn
        - Selection
        - IntProperty
        - LongProperty
        - DecimalProperty
        - BoolProperty
        - DateTimeProperty
        - DateTimeOffsetProperty
        - StringProperty
        - Relation
        - RelationExists
        - Ancestor
      type: string
      description: Specifies the type of filter to be applied in a query node.
    QuerySortOrder:
      enum:
        - Desc
        - Asc
      type: string
    RelationExistsQueryNodeFilter:
      allOf:
        - $ref: '#/components/schemas/QueryNodeFilter'
        - required:
            - relation
            - role
          type: object
          properties:
            relation:
              minLength: 1
              type: string
              description: Gets or sets the relation.
            role:
              $ref: '#/components/schemas/RelationRole'
            type:
              $ref: '#/components/schemas/QueryNodeFilterType'
          additionalProperties: false
      description: A query for entities using a specified relation filter.
    RelationLoadOption:
      type: object
      properties:
        load_option:
          $ref: '#/components/schemas/LoadOption'
        relations:
          type: array
          items:
            $ref: '#/components/schemas/RelationSpecification'
          description: "Gets or sets a list of relations that need to be loaded.\r\nThis is only useful when Stylelabs.M.Base.Entities.Loading.RelationLoadOption.LoadOption is Stylelabs.M.Base.Entities.Loading.LoadOption.Custom."
          nullable: true
        max_related_items:
          type: integer
          description: Gets or sets the maximum number of related items for each relation.
          format: int32
          nullable: true
      additionalProperties: false
      description: Represents options for loading relations.
    RelationQueryNodeFilter:
      allOf:
        - $ref: '#/components/schemas/QueryNodeFilter'
        - required:
            - id
            - relation
            - role
          type: object
          properties:
            relation:
              minLength: 1
              type: string
              description: Gets or sets the relation.
            role:
              $ref: '#/components/schemas/RelationRole'
            id:
              type: integer
              description: Gets or sets the ID.
              format: int64
            type:
              $ref: '#/components/schemas/QueryNodeFilterType'
          additionalProperties: false
      description: A query for entities using a specified relation filter.
    RelationRole:
      enum:
        - Parent
        - Child
      type: string
    RelationSpecification:
      type: object
      properties:
        name:
          type: string
          description: Name of the relation (case insensitive).
          nullable: true
        role:
          $ref: '#/components/schemas/RelationRole'
      additionalProperties: false
    RootTaxonomyItemQueryNodeFilter:
      allOf:
        - $ref: '#/components/schemas/QueryNodeFilter'
        - type: object
          properties:
            type:
              $ref: '#/components/schemas/QueryNodeFilterType'
          additionalProperties: false
      description: A query filter for entities that are root taxonomy.
    SearchAfterRequest:
      required:
        - filter
        - sorting
      type: object
      properties:
        filter:
          oneOf:
            - $ref: '#/components/schemas/AncestorIdQueryNodeFilter'
            - $ref: '#/components/schemas/CreatedByQueryNodeFilter'
            - $ref: '#/components/schemas/DefinitionIdQueryNodeFilter'
            - $ref: '#/components/schemas/DefinitionNameQueryNodeFilter'
            - $ref: '#/components/schemas/FullTextQueryNodeFilter'
            - $ref: '#/components/schemas/IdentifierQueryNodeFilter'
            - $ref: '#/components/schemas/IdInQueryNodeFilter'
            - $ref: '#/components/schemas/LockedByQueryNodeFilter'
            - $ref: '#/components/schemas/LockedQueryNodeFilter'
            - $ref: '#/components/schemas/LogicalQueryNodeFilter'
            - $ref: '#/components/schemas/ModifiedByQueryNodeFilter'
            - $ref: '#/components/schemas/NegatingQueryNodeFilter'
            - $ref: '#/components/schemas/PathRootQueryNodeFilter'
            - $ref: '#/components/schemas/ObjectPropertyQueryNodeFilter'
            - $ref: '#/components/schemas/RelationExistsQueryNodeFilter'
            - $ref: '#/components/schemas/RelationQueryNodeFilter'
            - $ref: '#/components/schemas/RootTaxonomyItemQueryNodeFilter'
            - $ref: '#/components/schemas/SelectionQueryNodeFilter'
          description: Base query filter for entities.
        take:
          type: integer
          description: >-
            The number of items to take. If not specified, the underlying
            implementation will use a default value.
          format: int32
          default: 25
          nullable: true
        sorting:
          type: array
          items:
            $ref: '#/components/schemas/Sorting'
          description: Defines how the results should be sorted.
        search_after:
          type: array
          items:
            type: string
          description: "To retrieve the next page of results using a set of sort values from the previous results.\r\nFor example, if you make a request and receive 100 items, ending with entity_id_1,\r\nyour subsequent call can include search_after=entity_id_1 to fetch the next page."
          nullable: true
        renditions:
          type: array
          items:
            type: string
          description: The renditions that will be loaded with the resulting entities.
          nullable: true
          deprecated: true
        nested_relations:
          type: array
          items:
            type: string
          description: >-
            The nested relations that will be loaded with the resulting
            entities.
          nullable: true
          deprecated: true
        load_configuration:
          $ref: '#/components/schemas/EntityLoadConfiguration'
      additionalProperties: false
      description: Request for executing queries with pagination.
    SelectionQueryNodeFilter:
      allOf:
        - $ref: '#/components/schemas/QueryNodeFilter'
        - required:
            - definition_name
          type: object
          properties:
            selection_pool_id:
              type: integer
              description: Gets or sets the selection pool id.
              format: int64
              nullable: true
            selection_pool:
              type: string
              description: Gets or sets the selection pool.
              nullable: true
            definition_name:
              minLength: 1
              type: string
              description: Gets or sets the definition name.
            sub_pool_id:
              type: integer
              description: Gets or sets the sub pool id.
              format: int64
              nullable: true
            type:
              $ref: '#/components/schemas/QueryNodeFilterType'
          additionalProperties: false
      description: A query for entities using a specified selection filter.
    SortFieldType:
      enum:
        - Property
        - System
      type: string
    Sorting:
      required:
        - field
        - order
      type: object
      properties:
        field_type:
          $ref: '#/components/schemas/SortFieldType'
        field:
          type: string
        culture:
          type: string
          nullable: true
        order:
          $ref: '#/components/schemas/QuerySortOrder'
      additionalProperties: false
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: /oauth/token
          scopes: {}
        authorizationCode:
          authorizationUrl: /oauth/authorize
          tokenUrl: /oauth/token
          scopes: {}
