openapi: 3.0.1
info:
  title: Entities API
  description: >
    Use the Entities API to retrieve, create, update, and delete entities. An
    entity is a set of data that belongs together (such as for a product,
    campaign, project, story, recipe, or asset). 


    ## Authentication


    To use the <b>Try it</b> feature of the Entities 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. 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)
       {% admonition type="info" name="Note" %}A [Copy method](https://doc.sitecore.com/ch/en/developers/cloud-dev/entity-1523348.html) is also available. {% /admonition %} 
  version: v1.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: Entities
    description: 'The Entities endpoint is used to manage entities.  '
paths:
  /api/entities/{id}:
    get:
      tags:
        - Entities
      summary: Retrieve an entity using its ID
      description: >-
        Retrieves an entity using its ID and loads related data, including
        entity properties, member groups, renditions, permissions, and so on.
        You can also specify cultures for multi-language support.
      operationId: EntityById
      parameters:
        - name: id
          in: path
          description: The ID for the entity, for example, `39752`.
          required: true
          schema:
            type: integer
            format: int64
        - name: culture
          in: query
          description: >-
            Culture of the entity you want to load, for example `en-US` . If no
            culture is provided, multi-language properties are not included. Use
            the `cultures` parameter to retrieve the entity in multiple
            cultures.
          schema:
            type: string
        - name: groups
          in: query
          description: Member groups to include, for example, `PreambleGroup,ChoiceGroup`.
          schema:
            type: string
        - name: members
          in: query
          description: >-
            Members to include, for example,
            `PreambleThemeProperty,ChoiceThemeProperty`.
          schema:
            type: string
        - name: renditions
          in: query
          description: >-
            Renditions to include (comma-separated list), for example
            `Thumbnail,Preview`.
          schema:
            type: string
        - name: nestedRelations
          in: query
          description: >-
            Related entities to load directly instead of being referenced by a
            URL, for example `ParentRelation,ChildRelation`.
          schema:
            type: array
            items:
              type: string
        - name: loadPermissions
          in: query
          description: >-
            Whether to include all permissions the user has on the entity, for
            example `true` or `false`.
          schema:
            type: boolean
            default: false
        - name: cultures
          in: query
          description: >-
            Cultures in which to load the entity. The culture parameter can
            still specify a culture, even if this parameter is missing, for
            example `true` or `false`.
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityResource'
        '301':
          description: Redirected (Moved permanently). Applies only to light entities.
        '400':
          description: >-
            Request or Entity ID not valid (for example, less than or equal to
            zero or does not exist), or at least one culture is null.
        '401':
          description: Unauthorized request
        '404':
          description: Entity not found or user not authorized
      security:
        - oauth2: []
    put:
      tags:
        - Entities
      summary: Update an entity using its ID
      description: >-
        Updates an entity with the new details provided, including properties,
        relations, associated members and groups, and so on. Properties or
        relations not included in the request will be set to null.
      operationId: UpdateEntity
      parameters:
        - name: id
          in: path
          description: The ID of the entity to update, for example, `39752`.
          required: true
          schema:
            pattern: \d+
            type: integer
            format: int64
        - name: culture
          in: query
          description: User culture for the entity, for example `en-US`, `fr-CA`.
          schema:
            type: string
        - name: groups
          in: query
          description: >-
            Member groups to associate with the entity, for example
            `PreambleGroup,ChoiceGroup`.
          schema:
            type: string
        - name: members
          in: query
          description: >-
            Members to associate with the entity, for example
            `PreambleThemeProperty,ChoiceThemeProperty`.
          schema:
            type: string
        - name: cultures
          in: query
          description: >-
            Cultures to load, for example `en-US`. If provided, it overrides the
            culture parameter.
          schema:
            type: array
            items:
              type: string
      requestBody:
        description: The new details of the entity.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntityResource'
        required: true
      responses:
        '200':
          description: Successful operation
        '400':
          description: >-
            Request or Entity ID not valid (for example, less than or equal to
            zero or does not exist), or at least one culture is null.
        '401':
          description: Unauthorized request
        '404':
          description: Entity not found or user not authorized
      security:
        - oauth2: []
    delete:
      tags:
        - Entities
      summary: Delete an entity using its ID
      description: Deletes an entity with the specified ID.
      operationId: DeleteEntity
      parameters:
        - name: id
          in: path
          description: The unique ID of the entity to be deleted, for example, `39752`.
          required: true
          schema:
            pattern: \d+
            type: integer
            format: int64
      responses:
        '200':
          description: Entity successfully deleted
        '401':
          description: Unauthorized request
        '404':
          description: Entity not found or user not authorized
      security:
        - oauth2: []
  /api/entities/identifier/{identifier}:
    get:
      tags:
        - Entities
      summary: Retrieve an entity using its identifier
      description: >-
        Retrieves an entity with the specified identifier, including related
        data such as properties, member groups, renditions, permissions, and so
        on.
      operationId: EntityByIdentifier
      parameters:
        - name: identifier
          in: path
          description: >-
            The identifier for the entity, for example,
            `asset.VIPeventfruitbowl`.
          required: true
          schema:
            type: string
            pattern: ^[a-zA-Z0-9]+$
        - name: culture
          in: query
          description: >-
            Culture in which to load the entity, for example `en-US`. If no
            culture is provided, multi-language properties are not included.
          schema:
            type: string
        - name: groups
          in: query
          description: Member groups to include, for example `PreambleGroup,ChoiceGroup`.
          schema:
            type: string
        - name: members
          in: query
          description: >-
            Members to include, for example
            `PreambleThemeProperty,ChoiceThemeProperty`.
          schema:
            type: string
        - name: renditions
          in: query
          description: >-
            Renditions to include (comma-separated list), for example
            `Thumbnail,Preview`.
          schema:
            type: string
        - name: nestedRelations
          in: query
          description: >-
            Related entities to load directly instead of being referenced by a
            URL.
          schema:
            type: array
            items:
              type: string
        - name: loadPermissions
          in: query
          description: Whether to include all permissions the user has on the entity.
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityResource'
        '301':
          description: Redirected (Moved permanently). Applies only to light entities.
        '400':
          description: >-
            Request or Entity identifier not valid (for example, less than or
            equal to zero or does not exist).
        '401':
          description: Unauthorized request
        '404':
          description: Entity not found or user not authorized
      security:
        - oauth2: []
    put:
      tags:
        - Entities
      summary: Update an entity using its identifier
      description: >-
        Updates an entity with the new details provided, including properties,
        relations, associated members and groups, and so on. Properties or
        relations not included in the request will be set to null.
      operationId: UpdateEntityByIdentifier
      parameters:
        - name: identifier
          in: path
          description: >-
            The unique identifier of the entity to update, for example,
            `asset.VIPeventfruitbowl`.
          required: true
          schema:
            type: string
        - name: culture
          in: query
          description: User culture for the entity, for example `en-US`.
          schema:
            type: string
        - name: groups
          in: query
          description: >-
            Member groups to associate with the entity, for example
            `PreambleGroup,ChoiceGroup`.
          schema:
            type: string
        - name: members
          in: query
          description: >-
            Members to associate with the entity, for example
            `PreambleThemeProperty,ChoiceThemeProperty`.
          schema:
            type: string
      requestBody:
        description: The new details of the entity to be updated.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntityResource'
        required: true
      responses:
        '200':
          description: Entity successfully updated
        '400':
          description: >-
            Request not valid (for example, entity ID not found), or update
            resource is null.
        '401':
          description: Unauthorized request
        '404':
          description: Entity not found or user not authorized
      security:
        - oauth2: []
    delete:
      tags:
        - Entities
      summary: Delete an entity using its identifier
      description: Deletes an entity with the specified identifier.
      operationId: DeleteEntityByIdentifier
      parameters:
        - name: identifier
          in: path
          description: >-
            The unique identifier of the entity to be deleted,  for example,
            `asset.VIPeventfruitbowl`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Entity successfully deleted
        '401':
          description: Unauthorized request
        '404':
          description: Entity not found or user not authorized
      security:
        - oauth2: []
  /api/entitydefinitions/{name}/entities:
    get:
      tags:
        - Entities
      summary: Retrieve a list of all entities for a specific entity definition
      description: Lists all entities for the specified entity definition.
      operationId: EntitiesByDefinition
      parameters:
        - name: name
          in: path
          description: >-
            Entity definition name to use when filtering the entities, for
            example `M.Asset`.
          required: true
          schema:
            type: string
        - name: skip
          in: query
          description: >-
            Number of entities to skip before retrieving results, for example
            `1`.
          schema:
            type: integer
            format: int32
        - name: take
          in: query
          description: Number of entities to retrieve, for example `2`.
          schema:
            type: integer
            format: int32
        - name: culture
          in: query
          description: User culture in which to load the entities, for example `en-US`.
          schema:
            type: string
        - name: filter
          in: query
          description: >-
            Additional filters to apply when retrieving entities, for example
            `status:active AND type:image`.
          schema:
            type: string
        - name: groups
          in: query
          description: >-
            Member groups to include in the retrieved entities, for example
            `PreambleGroup,ChoiceGroup`.
          schema:
            type: string
        - name: members
          in: query
          description: >-
            Members to include in the retrieved entities, for example
            `PreambleThemeProperty,ChoiceThemeProperty`.
          schema:
            type: string
        - name: nestedRelations
          in: query
          description: >-
            Related entities to include fully loaded in the result, for example
            `AssetRelation,ChildAssetRelation`.
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityCollectionResource'
        '400':
          description: >-
            Request or Entity definition is not valid (for example, less than or
            equal to zero or does not exist), or at least one culture is null.
        '401':
          description: Unauthorized request
        '404':
          description: Entity not found or user not authorized
      security:
        - oauth2: []
  /api/entities:
    post:
      tags:
        - Entities
      summary: Create an entity
      description: >-
        Creates an entity with the specified details, including associated
        members and groups. The link to the associated `Entity Definition
        Resource` is required. The `self` property is ignored and may be
        omitted. <br> <br> If the request body contains an `id`, the request is
        treated as a possible `UPSERT`. If the `id` is omitted and only an
        `identifier` is provided, the request returns a conflict instead of
        updating the existing entity. The request then checks for the existence
        of the entity and if the response is positive, then it updates the
        entity based on the provided body elements. When an `id` is present, the
        header contains the same `Location` property as with a normal `POST`
        response. When an `identifier` is used, the header contains an
        `X-Global-Identifier` property with the updated identifier as its value.
        <br> <br> Use the [Upload
        API](https://doc.sitecore.com/ch/en/developers/cloud-dev/upload.html) to
        upload assets to Content Hub. {% admonition type="info" name="Note" %}It
        is not possible to set relations while creating an entity unless the
        relations are nested. Additionally, this functionality is available only
        through the REST API and not through the Web Client SDK. For non-nested
        relations one call is made for each relation that is updated. {%
        /admonition %}
      operationId: AddEntity
      parameters:
        - name: culture
          in: query
          description: Culture for the entity, for example `en-US`.
          schema:
            type: string
        - name: groups
          in: query
          description: >-
            Member groups to associate with the entity, for example
            `PreambleGroup,ChoiceGroup`.
          schema:
            type: string
        - name: members
          in: query
          description: >-
            Members to associate with the entity, for example
            `PreambleThemeProperty,ChoiceThemeProperty`.
          schema:
            type: string
      requestBody:
        description: Details of the entity to be added.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntityPostResource'
        required: true
      responses:
        '200':
          description: Successful operation
        '400':
          description: >-
            Request not valid(for example, less than or equal to zero), or
            target resource is null.
        '401':
          description: Unauthorized request
        '404':
          description: Entity not found or user not authorized
      security:
        - oauth2: []
components:
  schemas:
    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
    EntityLink:
      type: object
      properties:
        properties:
          type: object
          additionalProperties:
            type: object
            nullable: true
          description: Gets or sets the nested properties of the entity link.
          nullable: true
        renditions:
          type: object
          additionalProperties:
            type: object
            nullable: true
          description: Gets or sets the nested renditions of the entity link.
          nullable: true
        permissions:
          type: array
          items:
            type: string
          description: Gets or sets the nested permissions of the entity link.
          nullable: true
        identifier:
          type: string
          description: Gets or sets the nested identifier of the entity link.
          nullable: true
        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 an entity with additional properties, renditions,
        permissions, and identifier.
    EntityPostResource:
      type: object
      properties:
        id:
          type: integer
          description: Gets or sets the entity ID.
          format: int64
          nullable: true
        identifier:
          type: string
          description: Gets or sets the entity identifier.
          nullable: true
        properties:
          type: object
          additionalProperties:
            type: object
            nullable: true
          description: Gets or sets the properties of the entity.
          nullable: true
        relations:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/RelationResource'
          description: Gets or sets the relations of the entity.
          nullable: true
        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
        entitydefinition:
          $ref: '#/components/schemas/Link'
        is_system_owned:
          type: boolean
          description: Gets or sets a value indicating whether the entity is system owned.
        inherits_security:
          type: boolean
          description: >-
            Gets or sets a value indicating whether the entity inherits
            security.
        self:
          $ref: '#/components/schemas/Link'
      additionalProperties: false
      description: Represents a resource for creating 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, for example,
            `asset.VIPeventfruitbowl`.
          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.
    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.
    RelationResource:
      type: object
      properties:
        parents:
          type: array
          items:
            $ref: '#/components/schemas/EntityLink'
          description: The relation parents.
          nullable: true
        parent:
          $ref: '#/components/schemas/EntityLink'
        children:
          type: array
          items:
            $ref: '#/components/schemas/EntityLink'
          description: The relation children.
          nullable: true
        child:
          $ref: '#/components/schemas/EntityLink'
        inherits_security:
          type: boolean
          description: A value indicating whether the relation inherits security.
          nullable: true
        parent_total:
          type: integer
          description: >-
            Displays the total number of parents in the resource when the
            relation resource is limited.
          format: int64
          nullable: true
        child_total:
          type: integer
          description: >-
            Displays the total number of children in the resource when the
            relation resource is limited.
          format: int64
          nullable: true
        self:
          $ref: '#/components/schemas/Link'
      additionalProperties: false
      description: Represents an relation resource.
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: /oauth/authorize
          tokenUrl: /oauth/token
          scopes: {}
