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 specific criteria.
    <br><br> When using the Querying API, keep the following considerations in
    mind:

    - Due to deep paging considerations the querying endpoint is limited to
    retrieve up to 10,000 results.

    - When search results are sorted on a property and there are multiple
    results that have the same value for that property, then those results are
    displayed in random order.

    - With full-text search, do not use the following characters: `«`, `»`,
    `÷`,`×`, `¦`, `¤`, `⋇`, or `؉`. Do not combine special characters and
    wildcards within the same word. For example, use invoice re*ort instead of
    invoice-re*ort to ensure consistent results like invoice-report.

    - The <i>FullText</i> search property only supports the `==` operator, but
    can be negated.

    - When you run a query, make sure you include all the entity members that
    you want to retrieve. If you omit the members parameter, the response will
    return all the existing entity members (all properties, all relations, and
    so on). To ensure optimal performance, only request the members you actually
    need.

    - The API is configured to only load the related paths that are specified in
    a query. If you don't specify related path relations in your query, the
    response won't return any.
      
    ## 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 your mouse
      over the variable in the <b>Try it</b> pane and then clicking <b>Edit</b>.

    - An access token and the client ID. 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 using the API
      itself](https://doc.sitecore.com/ch/en/developers/cloud-dev/oauth-tokens.html#grant-flows).
  version: v3.0
  license:
    name: closed source
    url: https://www.sitecore.com
  x-metadata:
    product: Content Hub
servers:
  - url: https://{server}
    variables:
      server:
        default: your-server
security:
  - OAuth2.0: []
tags:
  - name: Querying
    description: >-
      The Querying API is responsible for fetching multiple pages of results
      sequentially.
paths:
  /api/entities/query:
    post:
      tags:
        - Querying
      summary: Retrieve entities using a query string
      description: Lists entities that match the query in a request body.
      operationId: EntitiesByQueryV3
      requestBody:
        description: The query request.
        content:
          application/json-patch+json:
            schema:
              $ref: '#/components/schemas/QueryRequest'
          application/json:
            schema:
              $ref: '#/components/schemas/QueryRequest'
          text/json:
            schema:
              $ref: '#/components/schemas/QueryRequest'
          application/*+json:
            schema:
              $ref: '#/components/schemas/QueryRequest'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResultResource'
        '400':
          description: Request is not valid
        '401':
          description: Unauthorized request or invalid access token
      security:
        - OAuth2.0: []
  /api/entities/scroll:
    post:
      tags:
        - Querying
      summary: Retrieve entities using a scroll-based query
      description: >-
        Lists all entities using a scroll-based query for efficient large result
        set traversal.
      operationId: EntitiesByScrollV3
      requestBody:
        description: The scroll.
        content:
          application/json-patch+json:
            schema:
              $ref: '#/components/schemas/ScrollRequest'
          application/json:
            schema:
              $ref: '#/components/schemas/ScrollRequest'
          text/json:
            schema:
              $ref: '#/components/schemas/ScrollRequest'
          application/*+json:
            schema:
              $ref: '#/components/schemas/ScrollRequest'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResultResource'
        '400':
          description: Request is not valid
        '401':
          description: Unauthorized request or invalid access token
      security:
        - OAuth2.0: []
  /api/entities/searchAfter:
    post:
      tags:
        - Querying
      summary: Retrieve entities using a search query
      description: >-
        Lists all entities that match the criteria. This endpoint supports
        sorted pagination using the `search-after` property.
      operationId: EntitiesBySearchAfterV3
      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.0: []
components:
  schemas:
    QueryRequest:
      type: object
      properties:
        query:
          $ref: '#/components/schemas/Query'
        load_configuration:
          $ref: '#/components/schemas/EntityLoadConfiguration'
      additionalProperties: false
      description: >-
        Represents a request to execute a query, inheriting from
        `Stylelabs.M.Base.Web.Api.Controllers.Querying.QueryLoadingResource`.
    QueryResultResource:
      type: object
      properties:
        scroll_id:
          type: string
          nullable: true
        items:
          type: array
          items:
            $ref: '#/components/schemas/SearchDocumentResource'
          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'
    ScrollRequest:
      type: object
      properties:
        scroll_id:
          type: string
          description: The ID of the scroll session to get the next results for.
          nullable: true
        scroll_time:
          type: string
          description: The time to keep the scroll session active.
          format: date-span
        load_configuration:
          $ref: '#/components/schemas/EntityLoadConfiguration'
      additionalProperties: false
    SearchAfterRequest:
      required:
        - filter
        - sorting
      type: object
      properties:
        filter:
          oneOf:
            - $ref: '#/components/schemas/QueryNodeFilter'
            - $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'
        sorting:
          type: array
          items:
            $ref: '#/components/schemas/Sorting'
        search_after:
          type: array
          items:
            type: string
          nullable: true
        take:
          type: integer
          format: int32
          nullable: true
        load_configuration:
          $ref: '#/components/schemas/EntityLoadConfiguration'
      additionalProperties: false
    EntityCollectionResource:
      type: object
      properties:
        last_hit_data:
          type: array
          items:
            type: string
          description: >-
            The last returned hits, 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
    Query:
      type: object
      properties:
        filter:
          $ref: '#/components/schemas/QueryFilter'
        skip:
          type: integer
          format: int32
          nullable: true
        take:
          type: integer
          format: int32
          nullable: true
        sorting:
          type: array
          items:
            $ref: '#/components/schemas/Sorting'
          nullable: true
        scroll_time:
          type: string
          format: date-span
          nullable: true
      additionalProperties: false
    QueryFilter:
      required:
        - type
      type: object
      properties:
        type:
          $ref: '#/components/schemas/FilterType'
      additionalProperties: false
    QueryNodeFilter:
      required:
        - type
      type: object
      properties:
        type:
          $ref: '#/components/schemas/QueryNodeFilterType'
      additionalProperties: false
      description: Base query filter for entities.
    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.
    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.
    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.
    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.
    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.
    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.
    LogicalQueryNodeFilter:
      allOf:
        - $ref: '#/components/schemas/QueryNodeFilter'
        - required:
            - left
            - operator
            - right
          type: object
          properties:
            left:
              oneOf:
                - $ref: '#/components/schemas/QueryNodeFilter'
                - $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'
              description: Gets or sets the left operant.
            right:
              oneOf:
                - $ref: '#/components/schemas/QueryNodeFilter'
                - $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'
              description: Gets or sets the right operant.
            operator:
              $ref: '#/components/schemas/LogicalOperator'
            type:
              $ref: '#/components/schemas/QueryNodeFilterType'
          additionalProperties: false
      description: A logical query filter.
    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.
    FilterType:
      enum:
        - Composite
        - Not
        - Property
        - Relation
        - CreatedBy
        - ModifiedBy
        - SecuredAncestors
        - Id
        - Identifier
        - Definition
        - Modules
        - CreatedOn
        - ModifiedOn
      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
    SortFieldType:
      enum:
        - Property
        - System
      type: string
    QuerySortOrder:
      enum:
        - Desc
        - Asc
      type: string
    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: string
            nullable: true
          description: The properties of the entity.
          nullable: true
        relations:
          type: object
          additionalProperties:
            type: string
            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 permissions.
          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.
    SearchDocumentResource:
      type: object
      properties:
        link:
          $ref: '#/components/schemas/Link'
        entity:
          $ref: '#/components/schemas/EntityResource'
        self:
          $ref: '#/components/schemas/Link'
      additionalProperties: false
    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.
    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.
    CultureLoadOption:
      type: object
      properties:
        load_option:
          $ref: '#/components/schemas/LoadOption'
        cultures:
          type: array
          items:
            type: string
          description: >-
            Gets or sets a list of culture names that need to be loaded. This 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.
    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.
    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.
    LoadOption:
      enum:
        - None
        - Default
        - Custom
        - All
      type: string
      description: An enum of possible load options.
      deprecated: true
    RelationSpecification:
      type: object
      properties:
        name:
          type: string
          description: Name of the relation (case insensitive).
          nullable: true
        role:
          $ref: '#/components/schemas/RelationRole'
      additionalProperties: false
    RelationRole:
      enum:
        - Parent
        - Child
      type: string
    LogicalOperator:
      enum:
        - And
        - Or
        - AndNot
      type: string
  securitySchemes:
    OAuth2.0:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: /oauth/token
          scopes: {}
        authorizationCode:
          authorizationUrl: /oauth/authorize
          tokenUrl: /oauth/token
          scopes: {}
