openapi: 3.1.0
info:
  title: Sitecore Content Hub REST API
  description: >-
    The Sitecore Content Hub REST API is a hypermedia API built on HTTP that
    provides programmatic access to the full range of Content Hub resources,
    including entities, assets, jobs, search, selections, upload, and audit logs.
    Developers use it to automate digital asset management workflows, migrate
    content, build custom integrations, and manage Content Hub configuration.
    The API supports standard CRUD operations and is authenticated using OAuth 2.0
    tokens obtained from the Content Hub identity provider. Navigation between
    resources uses hyperlinks rather than hardcoded URL patterns. The base URL is
    tenant-specific and corresponds to the URL of the Content Hub instance followed
    by /api/.
  version: 'v1'
  contact:
    name: Sitecore Support
    url: https://www.sitecore.com/support
  termsOfService: https://www.sitecore.com/legal/terms-of-service
externalDocs:
  description: Sitecore Content Hub REST API Documentation
  url: https://doc.sitecore.com/ch/en/developers/cloud-dev/rest-apis.html
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
tags:
  - name: Audit
    description: >-
      Endpoints for retrieving and querying audit log entries that track changes
      to entities and configuration within the Content Hub instance.
  - name: Download Orders
    description: >-
      Endpoints for creating and managing download orders that package assets
      for delivery, supporting both single and batch asset downloads.
  - name: Entities
    description: >-
      Endpoints for performing CRUD operations on Content Hub entities including
      assets, taxonomy nodes, content items, and all other entity types managed
      within the platform.
  - name: Jobs
    description: >-
      Endpoints for managing background job targets including retrieval, creation,
      update, and deletion of job configurations.
  - name: Querying
    description: >-
      Endpoints for fetching entities that match specific criteria using structured
      query expressions against entity properties and relations.
  - name: Search
    description: >-
      Endpoints for executing search queries against the Content Hub entity index,
      retrieving facet values, and managing search filters.
  - name: Selections
    description: >-
      Endpoints for managing entity selections across selection pools, allowing
      grouping of entities for bulk operations or editorial workflows.
  - name: Upload
    description: >-
      Endpoints for uploading digital assets into Content Hub, including creating
      upload requests, uploading binary content, and completing asset ingest.
security:
  - bearerAuth: []
paths:
  /entities:
    get:
      operationId: listEntities
      summary: List entities
      description: >-
        Retrieves a paginated list of entities from the Content Hub. Supports
        filtering by entity definition, property values, and relations. The
        response includes hyperlinks for navigating to related resources.
      tags:
        - Entities
      parameters:
        - name: definition
          in: query
          description: Filter entities by their entity definition identifier
          required: false
          schema:
            type: string
        - name: skip
          in: query
          description: Number of entities to skip for pagination
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
        - name: take
          in: query
          description: Maximum number of entities to return
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
        - name: culture
          in: query
          description: Culture code for multi-lingual property values (e.g., en-US)
          required: false
          schema:
            type: string
      responses:
        '200':
          description: A paginated list of entities
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createEntity
      summary: Create an entity
      description: >-
        Creates a new entity in Content Hub according to the specified entity
        definition. The entity type is determined by the definition identifier
        provided in the request body. Properties and relations are set according
        to the definition schema.
      tags:
        - Entities
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEntityRequest'
      responses:
        '201':
          description: Entity created successfully
          headers:
            Location:
              description: The URL of the newly created entity
              schema:
                type: string
                format: uri
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Entity'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /entities/{id}:
    get:
      operationId: getEntity
      summary: Get an entity
      description: >-
        Retrieves a specific entity by its numeric identifier. Returns the entity
        with all its properties, relations, and hypermedia links. Use the culture
        parameter to retrieve localized property values.
      tags:
        - Entities
      parameters:
        - $ref: '#/components/parameters/entityId'
        - name: culture
          in: query
          description: Culture code for localized properties (e.g., en-US)
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Entity details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Entity'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateEntity
      summary: Update an entity
      description: >-
        Performs a full replacement update of an entity. All properties and
        relations are replaced with the values in the request body. Missing
        optional properties will be cleared.
      tags:
        - Entities
      parameters:
        - $ref: '#/components/parameters/entityId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEntityRequest'
      responses:
        '200':
          description: Entity updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Entity'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteEntity
      summary: Delete an entity
      description: >-
        Permanently deletes an entity from Content Hub. This operation is
        irreversible. Assets that are in use or have active relations may
        require the relations to be removed first.
      tags:
        - Entities
      parameters:
        - $ref: '#/components/parameters/entityId'
      responses:
        '204':
          description: Entity deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /entities/{id}/lifecycle:
    put:
      operationId: updateEntityLifecycle
      summary: Update entity lifecycle state
      description: >-
        Updates the lifecycle state of an entity such as an asset. Lifecycle
        state transitions control the publishing workflow of assets within
        Content Hub (e.g., Draft, Approved, Published).
      tags:
        - Entities
      parameters:
        - $ref: '#/components/parameters/entityId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LifecycleRequest'
      responses:
        '200':
          description: Lifecycle state updated
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /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'

  /search:
    post:
      operationId: searchEntities
      summary: Search entities
      description: >-
        Executes a full-text and structured search query across the Content Hub
        entity index. Returns matching entities with facet aggregations for
        interactive filtering. Supports relevance ranking and pagination.
      tags:
        - Search
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
      responses:
        '200':
          description: Search results with facets
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /upload:
    post:
      operationId: createUploadRequest
      summary: Create an upload request
      description: >-
        Initiates a new asset upload into Content Hub by creating an upload
        request. Returns a target URL and upload identifier used for the
        subsequent binary file upload step.
      tags:
        - Upload
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UploadRequest'
      responses:
        '200':
          description: Upload request created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /jobs:
    get:
      operationId: listJobs
      summary: List jobs
      description: >-
        Retrieves a list of background job targets configured in the Content Hub
        instance. Jobs handle long-running operations such as asset processing,
        reporting, and data exports.
      tags:
        - Jobs
      parameters:
        - name: skip
          in: query
          description: Number of jobs to skip for pagination
          required: false
          schema:
            type: integer
            minimum: 0
        - name: take
          in: query
          description: Maximum number of jobs to return
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
      responses:
        '200':
          description: List of jobs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /selections:
    get:
      operationId: listSelections
      summary: List selections
      description: >-
        Retrieves all entity selections across selection pools. Selections group
        entities for bulk operations such as download, export, or editorial actions.
      tags:
        - Selections
      responses:
        '200':
          description: List of selections
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Selection'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createSelection
      summary: Create a selection
      description: >-
        Creates a new entity selection in a specified selection pool. Selections
        hold a list of entity identifiers for subsequent bulk operations.
      tags:
        - Selections
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSelectionRequest'
      responses:
        '201':
          description: Selection created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Selection'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /audit:
    get:
      operationId: listAuditEntries
      summary: List audit log entries
      description: >-
        Retrieves and queries audit log entries that record all changes made to
        entities and configuration within the Content Hub instance. Supports
        filtering by entity, user, date range, and operation type.
      tags:
        - Audit
      parameters:
        - name: entityId
          in: query
          description: Filter audit entries by entity identifier
          required: false
          schema:
            type: integer
        - name: userId
          in: query
          description: Filter audit entries by the user who made the change
          required: false
          schema:
            type: string
        - name: from
          in: query
          description: Start date for audit entry filtering (ISO 8601)
          required: false
          schema:
            type: string
            format: date-time
        - name: to
          in: query
          description: End date for audit entry filtering (ISO 8601)
          required: false
          schema:
            type: string
            format: date-time
        - name: skip
          in: query
          description: Number of entries to skip for pagination
          required: false
          schema:
            type: integer
        - name: take
          in: query
          description: Maximum number of entries to return
          required: false
          schema:
            type: integer
            maximum: 100
      responses:
        '200':
          description: List of audit log entries
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /downloadorders:
    post:
      operationId: createDownloadOrder
      summary: Create a download order
      description: >-
        Creates a download order that packages one or more assets for delivery.
        Download orders can specify renditions, file formats, and delivery options.
        The order is processed asynchronously and the download URL is provided
        upon completion.
      tags:
        - Download Orders
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDownloadOrderRequest'
      responses:
        '202':
          description: Download order accepted for processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DownloadOrder'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

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

  parameters:
    entityId:
      name: id
      in: path
      description: The numeric identifier of the entity
      required: true
      schema:
        type: integer

  responses:
    Unauthorized:
      description: Authentication token is missing or invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: The request body or parameters are invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: The requested resource was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'

  schemas:
    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

    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

    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

    CreateEntityRequest:
      type: object
      description: Request body for creating or updating an entity
      required:
        - definitionName
      properties:
        definitionName:
          type: string
          description: The name of the entity definition for the new entity
        identifier:
          type: string
          description: Optional custom string identifier for the entity
        cultures:
          type: array
          description: Culture codes for which to set localized properties
          items:
            type: string
        properties:
          type: object
          description: Property name to value mappings for the entity
          additionalProperties: true
        relations:
          type: object
          description: Relation name to entity reference mappings
          additionalProperties: true

    LifecycleRequest:
      type: object
      description: Request body for updating an entity's lifecycle state
      required:
        - state
      properties:
        state:
          type: string
          description: The target lifecycle state for the entity
          enum:
            - Draft
            - InProgress
            - Approved
            - Published
            - Archived

    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

    SearchRequest:
      type: object
      description: A search request for querying entities with faceting
      properties:
        query:
          type: string
          description: Full-text search query string
        filters:
          type: array
          description: Structured filters to apply to the search
          items:
            type: object
            additionalProperties: true
        skip:
          type: integer
          description: Number of results to skip
          default: 0
        take:
          type: integer
          description: Maximum number of results to return
          default: 25
        facets:
          type: array
          description: Facet field names to include in the response
          items:
            type: string

    SearchResponse:
      type: object
      description: Search results with facet aggregations
      properties:
        items:
          type: array
          description: Matching entities for the current page
          items:
            $ref: '#/components/schemas/Entity'
        totalCount:
          type: integer
          description: Total number of matching entities
        facets:
          type: object
          description: Facet aggregations keyed by facet field name
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/FacetValue'

    FacetValue:
      type: object
      description: A single facet value with its count in search results
      properties:
        value:
          type: string
          description: The facet value
        count:
          type: integer
          description: The number of matching entities with this value

    UploadRequest:
      type: object
      description: Request body for creating an asset upload request
      required:
        - fileName
        - fileSize
      properties:
        fileName:
          type: string
          description: The name of the file being uploaded
        fileSize:
          type: integer
          description: The size of the file in bytes
        fileType:
          type: string
          description: The MIME type of the file being uploaded
        culture:
          type: string
          description: The culture code for the asset metadata

    UploadResponse:
      type: object
      description: Response from creating an upload request with target URLs
      properties:
        uploadId:
          type: string
          description: The unique identifier for the upload session
        uploadUrl:
          type: string
          description: The URL to which the binary file content should be uploaded
          format: uri
        entityId:
          type: integer
          description: The identifier of the entity that will be created upon completion

    JobListResponse:
      type: object
      description: A paginated list of job configurations
      properties:
        items:
          type: array
          description: The job targets
          items:
            $ref: '#/components/schemas/Job'
        totalCount:
          type: integer
          description: Total number of jobs

    Job:
      type: object
      description: A background job target in Content Hub
      properties:
        id:
          type: integer
          description: The numeric identifier of the job
        identifier:
          type: string
          description: The string identifier of the job target
        status:
          type: string
          description: The current status of the job
          enum:
            - Queued
            - Running
            - Completed
            - Failed
        createdOn:
          type: string
          description: The ISO 8601 timestamp when the job was created
          format: date-time
        completedOn:
          type: string
          description: The ISO 8601 timestamp when the job completed
          format: date-time

    Selection:
      type: object
      description: A named selection pool containing entity identifiers
      properties:
        id:
          type: string
          description: The unique identifier of the selection
        name:
          type: string
          description: The name of the selection pool
        entityIds:
          type: array
          description: The entity identifiers included in this selection
          items:
            type: integer
        createdOn:
          type: string
          description: The ISO 8601 timestamp when the selection was created
          format: date-time

    CreateSelectionRequest:
      type: object
      description: Request body for creating a selection
      required:
        - entityIds
      properties:
        name:
          type: string
          description: Optional name for the selection pool
        entityIds:
          type: array
          description: Entity identifiers to include in the selection
          items:
            type: integer

    AuditListResponse:
      type: object
      description: A paginated list of audit log entries
      properties:
        items:
          type: array
          description: The audit entries for the current page
          items:
            $ref: '#/components/schemas/AuditEntry'
        totalCount:
          type: integer
          description: Total number of matching audit entries

    AuditEntry:
      type: object
      description: An audit log entry recording a change within Content Hub
      properties:
        id:
          type: integer
          description: The unique identifier of the audit entry
        entityId:
          type: integer
          description: The identifier of the entity that was changed
        userId:
          type: string
          description: The username of the user who made the change
        operation:
          type: string
          description: The type of operation performed
          enum:
            - Create
            - Update
            - Delete
            - LifecycleChange
        timestamp:
          type: string
          description: The ISO 8601 timestamp of the change
          format: date-time
        changes:
          type: object
          description: The property changes made during this operation
          additionalProperties: true

    DownloadOrder:
      type: object
      description: A download order packaging assets for delivery
      properties:
        id:
          type: string
          description: The unique identifier of the download order
        status:
          type: string
          description: The current processing status of the download order
          enum:
            - Queued
            - Processing
            - Completed
            - Failed
        downloadUrl:
          type: string
          description: The URL from which the packaged assets can be downloaded
          format: uri
        createdOn:
          type: string
          description: The ISO 8601 timestamp when the download order was created
          format: date-time
        completedOn:
          type: string
          description: The ISO 8601 timestamp when the download order was completed
          format: date-time

    CreateDownloadOrderRequest:
      type: object
      description: Request body for creating a download order
      required:
        - entityIds
      properties:
        entityIds:
          type: array
          description: Entity identifiers of assets to include in the download
          items:
            type: integer
        renditionName:
          type: string
          description: The name of the asset rendition to download (e.g., Original, Preview)
        includeMetadata:
          type: boolean
          description: Whether to include metadata alongside the asset files
          default: false

    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