openapi: 3.0.4
info:
  title: Contit API
  description: Cloud-based headless CMS and workspace management platform.
  contact:
    name: Overbi Srl
    url: https://www.contit.it
    email: supporto@contit.it
  version: '1.0'
servers:
  - url: https://api.contit.cloud
paths:
  '/contents/{contentTypeKey}':
    post:
      tags:
        - Content (V1)
      summary: Search contents
      description: 'Search and filter content items with pagination, ordering, localization, and nested filter groups.'
      operationId: Contents_Search
      parameters:
        - name: contentTypeKey
          in: path
          description: 'The content type key (e.g. ''Product'', ''Article'')'
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                page:
                  type: integer
                  description: Page number (1-based)
                pageSize:
                  type: integer
                  description: Number of items per page (max 500)
                filter:
                  type: string
                  description: Filter tree with nested groups and rules to restrict results
                order:
                  type: string
                  description: Sorting configuration
                locale:
                  type: string
                  description: 'Locale code for translated fields (e.g. ''en'', ''it'')'
                includeRelations:
                  type: array
                  description: Array of relation field keys whose related content should be expanded inline
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    description: Array of content items with typed field arrays
                  total:
                    type: integer
                    description: Total number of matching items
                  page:
                    type: integer
                    description: Current page number
                  pageSize:
                    type: integer
                    description: Items per page
                  totalPages:
                    type: integer
                    description: Total number of pages
                  hasMorePages:
                    type: boolean
                    description: Whether additional pages exist
        '401':
          description: Unauthorized — missing or invalid access token
      security:
        - ApiKey: [ ]
          Bearer: [ ]
    put:
      tags:
        - Content (V1)
      summary: Create or update content
      description: Create a new content item (id = null) or update an existing one. Returns the full content model including system-generated fields.
      operationId: Contents_CreateOrUpdate
      parameters:
        - name: contentTypeKey
          in: path
          description: The content type key
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: Content item ID. Pass null or omit to create a new item.
                contentType:
                  type: string
                  description: The content type key (must match path parameter)
                fields:
                  type: array
                  description: 'Array of typed fields with type, key, and value'
                clientInfo:
                  type: string
                  description: Optional client identifier for audit logging
        required: true
      responses:
        '200':
          description: Success — returns the saved content item with system fields populated
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Content item ID (generated if new)
                  contentType:
                    type: string
                    description: Content type key
                  fields:
                    type: array
                    description: Array of typed fields
                  createdAt:
                    type: string
                    description: Creation timestamp
                  updatedAt:
                    type: string
                    description: Last update timestamp
        '401':
          description: Unauthorized
      security:
        - ApiKey: [ ]
          Bearer: [ ]
  '/contents/{contentTypeKey}/ids':
    post:
      tags:
        - Content (V1)
      summary: Get content IDs only
      description: 'Returns only the IDs of matching content items, useful for bulk operations or cross-referencing without loading full content.'
      operationId: Contents_GetIds
      parameters:
        - name: contentTypeKey
          in: path
          description: 'The content type key (e.g. ''Product'', ''Article'')'
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                filter:
                  type: string
                  description: Filter tree to restrict results
                page:
                  type: integer
                  description: Page number (1-based)
                pageSize:
                  type: integer
                  description: Number of items per page
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  ids:
                    type: array
                    description: Array of content item IDs
                  total:
                    type: integer
                    description: Total number of matching items
        '401':
          description: Unauthorized
      security:
        - ApiKey: [ ]
          Bearer: [ ]
  '/contents/{contentTypeKey}/{id}':
    get:
      tags:
        - Content (V1)
      summary: Get single content
      description: Retrieve a single content item by its ID.
      operationId: Contents_GetById
      parameters:
        - name: contentTypeKey
          in: path
          description: The content type key
          required: true
          schema:
            type: string
        - name: id
          in: path
          description: The content item ID (GUID)
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Content item ID
                  contentType:
                    type: string
                    description: Content type key
                  fields:
                    type: array
                    description: Array of typed fields
                  createdAt:
                    type: string
                    description: Creation timestamp
                  updatedAt:
                    type: string
                    description: Last update timestamp
        '401':
          description: Unauthorized
        '404':
          description: Not Found — content item does not exist
      security:
        - ApiKey: [ ]
          Bearer: [ ]
    post:
      tags:
        - Content (V1)
      summary: Get content with relations
      description: 'Retrieve a single content item by ID, optionally expanding related content and specifying a locale for translated fields.'
      operationId: Contents_GetWithRelations
      parameters:
        - name: contentTypeKey
          in: path
          description: The content type key
          required: true
          schema:
            type: string
        - name: id
          in: path
          description: The content item ID (GUID)
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                locale:
                  type: string
                  description: 'Locale code for translated fields (e.g. ''en'', ''it'')'
                includeRelations:
                  type: array
                  description: Relation field keys to expand inline
        required: true
      responses:
        '200':
          description: Success — content item with expanded relations
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Content item ID
                  contentType:
                    type: string
                    description: Content type key
                  fields:
                    type: array
                    description: 'Array of typed fields, with relations expanded'
        '401':
          description: Unauthorized
        '404':
          description: Not Found
      security:
        - ApiKey: [ ]
          Bearer: [ ]
    delete:
      tags:
        - Content (V1)
      summary: Delete content
      description: Permanently delete a content item by its ID.
      operationId: Contents_Delete
      parameters:
        - name: contentTypeKey
          in: path
          description: The content type key
          required: true
          schema:
            type: string
        - name: id
          in: path
          description: The content item ID (GUID)
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success — content deleted
        '401':
          description: Unauthorized
        '404':
          description: Not Found
      security:
        - ApiKey: [ ]
          Bearer: [ ]
  '/contents/{contentTypeKey}/aggregate':
    post:
      tags:
        - Content (V1)
      summary: Aggregate field values
      description: 'Compute an aggregate (Sum, Avg, Min, Max, or Count) on a numeric field across matching content items.'
      operationId: Contents_Aggregate
      parameters:
        - name: contentTypeKey
          in: path
          description: The content type key
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                fieldKey:
                  type: string
                  description: The field key to aggregate on
                aggregateType:
                  type: string
                  description: 'Aggregation function: Sum, Avg, Min, Max, or Count'
                filter:
                  type: string
                  description: Optional filter to restrict which items are aggregated
        required: true
      responses:
        '200':
          description: Success — returns a single decimal value
          content:
            application/json:
              schema:
                type: object
                properties:
                  value:
                    type: number
                    description: The computed aggregate value
        '401':
          description: Unauthorized
      security:
        - ApiKey: [ ]
          Bearer: [ ]
  '/contents/{contentTypeKey}/aggregategroup':
    post:
      tags:
        - Content (V1)
      summary: Grouped aggregation
      description: 'Compute an aggregate grouped by a specific field, returning one result per distinct group value.'
      operationId: Contents_AggregateGroup
      parameters:
        - name: contentTypeKey
          in: path
          description: The content type key
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                fieldKey:
                  type: string
                  description: The field key to aggregate on
                aggregateType:
                  type: string
                  description: 'Aggregation function: Sum, Avg, Min, Max, or Count'
                groupByFieldKey:
                  type: string
                  description: The field key to group results by
                filter:
                  type: string
                  description: Optional filter to restrict which items are aggregated
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    description: Array of group-value / aggregate-value pairs
        '401':
          description: Unauthorized
      security:
        - ApiKey: [ ]
          Bearer: [ ]
  '/contents/{contentTypeKey}/encrypt/check':
    post:
      tags:
        - Content (V1)
      summary: Check encrypted field value
      description: Verify that an encrypted field matches a given plaintext value without revealing the stored data.
      operationId: Contents_EncryptCheck
      parameters:
        - name: contentTypeKey
          in: path
          description: The content type key
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: The content item ID
                encryptFields:
                  type: string
                  description: Dictionary of field key to plaintext value to check against
        required: true
      responses:
        '200':
          description: Success — returns true if values match
          content:
            application/json:
              schema:
                type: object
                properties:
                  match:
                    type: boolean
                    description: Whether the provided value matches the stored encrypted value
        '401':
          description: Unauthorized
        '404':
          description: Not Found
      security:
        - ApiKey: [ ]
          Bearer: [ ]
  '/contents/{contentTypeKey}/encrypt/decrypt':
    post:
      tags:
        - Content (V1)
      summary: Decrypt encrypted fields
      description: Decrypt one or more encrypted fields on a content item. Requires a valid TOTP code for additional security.
      operationId: Contents_EncryptDecrypt
      parameters:
        - name: contentTypeKey
          in: path
          description: The content type key
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: The content item ID
                encryptFieldKeys:
                  type: array
                  description: Array of field keys to decrypt
                totpCode:
                  type: string
                  description: Time-based one-time password for authorization
        required: true
      responses:
        '200':
          description: Success — returns decrypted field values
          content:
            application/json:
              schema:
                type: object
                properties:
                  fields:
                    type: string
                    description: Dictionary of field key to decrypted plaintext value
        '401':
          description: Unauthorized
        '403':
          description: Forbidden — invalid TOTP code
      security:
        - ApiKey: [ ]
          Bearer: [ ]
  '/contents/{contentTypeKey}/encrypt':
    put:
      tags:
        - Content (V1)
      summary: Set encrypted field values
      description: Store one or more field values in encrypted form on a content item.
      operationId: Contents_EncryptSet
      parameters:
        - name: contentTypeKey
          in: path
          description: The content type key
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: The content item ID
                encryptFields:
                  type: string
                  description: Dictionary of field key to plaintext value to encrypt and store
                clientInfo:
                  type: string
                  description: Optional client identifier for audit logging
        required: true
      responses:
        '200':
          description: Success — fields encrypted and stored
        '401':
          description: Unauthorized
        '404':
          description: Not Found
      security:
        - ApiKey: [ ]
          Bearer: [ ]
  '/contents/{contentTypeKey}/publish':
    put:
      tags:
        - Content (V1)
      summary: Publish content (deprecated)
      description: 'Deprecated. Use PUT /contents/{contentTypeKey} with the appropriate status field instead.'
      operationId: Contents_Publish_Deprecated
      parameters:
        - name: contentTypeKey
          in: path
          description: The content type key
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: The content item ID to publish
                clientInfo:
                  type: string
                  description: Optional client identifier
        required: true
      responses:
        '200':
          description: Success
        '401':
          description: Unauthorized
      deprecated: true
      security:
        - ApiKey: [ ]
          Bearer: [ ]
  '/v2/contents/{contentTypeKey}':
    post:
      tags:
        - Content (V2)
      summary: Search contents (V2)
      description: Search and filter content items using the V2 model where fields are a flat key-value dictionary and translations are separate.
      operationId: ContentsV2_Search
      parameters:
        - name: contentTypeKey
          in: path
          description: 'The content type key (e.g. ''Product'', ''Article'')'
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                page:
                  type: integer
                  description: Page number (1-based)
                pageSize:
                  type: integer
                  description: Number of items per page (max 500)
                filter:
                  type: string
                  description: Filter tree with nested groups and rules
                order:
                  type: string
                  description: Sorting configuration with fieldKey and sortDir
                locale:
                  type: string
                  description: Locale code for translated fields
                includeRelations:
                  type: array
                  description: Relation field keys to expand
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    description: Array of V2 content items with flat field dictionaries
                  total:
                    type: integer
                    description: Total matching items
                  page:
                    type: integer
                    description: Current page
                  pageSize:
                    type: integer
                    description: Items per page
                  totalPages:
                    type: integer
                    description: Total pages
                  hasMorePages:
                    type: boolean
                    description: Whether more pages exist
        '401':
          description: Unauthorized
      security:
        - ApiKey: [ ]
          Bearer: [ ]
    put:
      tags:
        - Content (V2)
      summary: Create or update content (V2)
      description: Create a new content item (omit id) or update an existing one using the V2 flat-dictionary model with separate translations.
      operationId: ContentsV2_CreateOrUpdate
      parameters:
        - name: contentTypeKey
          in: path
          description: The content type key
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: Content item ID. Omit or null to create a new item.
                fields:
                  type: string
                  description: Flat dictionary of field key to value
                translations:
                  type: string
                  description: Dictionary of field key to locale-value pairs for localized fields
                clientInfo:
                  type: string
                  description: Optional client identifier for audit logging
        required: true
      responses:
        '200':
          description: Success — returns the saved V2 content item
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Content item ID (generated if new)
                  fields:
                    type: string
                    description: Flat dictionary of field key to value
                  translations:
                    type: string
                    description: Translations dictionary
        '401':
          description: Unauthorized
      security:
        - ApiKey: [ ]
          Bearer: [ ]
  '/v2/contents/{contentTypeKey}/ids':
    post:
      tags:
        - Content (V2)
      summary: Get content IDs only (V2)
      description: Returns only the IDs of matching content items using V2 filtering.
      operationId: ContentsV2_GetIds
      parameters:
        - name: contentTypeKey
          in: path
          description: The content type key
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                filter:
                  type: string
                  description: Filter tree to restrict results
                page:
                  type: integer
                  description: Page number (1-based)
                pageSize:
                  type: integer
                  description: Number of items per page
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  ids:
                    type: array
                    description: Array of content item IDs
                  total:
                    type: integer
                    description: Total matching items
        '401':
          description: Unauthorized
      security:
        - ApiKey: [ ]
          Bearer: [ ]
  '/v2/contents/{contentTypeKey}/{id}':
    get:
      tags:
        - Content (V2)
      summary: Get single content (V2)
      description: Retrieve a single content item by ID using the V2 flat-dictionary model.
      operationId: ContentsV2_GetById
      parameters:
        - name: contentTypeKey
          in: path
          description: The content type key
          required: true
          schema:
            type: string
        - name: id
          in: path
          description: The content item ID (GUID)
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Content item ID
                  fields:
                    type: string
                    description: Flat dictionary of field key to value
                  translations:
                    type: string
                    description: Dictionary of field key to locale-value pairs
        '401':
          description: Unauthorized
        '404':
          description: Not Found
      security:
        - ApiKey: [ ]
          Bearer: [ ]
  '/preview-contents/{contentTypeKey}':
    post:
      tags:
        - Preview Content (V1)
      summary: Search preview contents
      description: 'Search and filter draft/preview content items with pagination, ordering, and localization.'
      operationId: PreviewContents_Search
      parameters:
        - name: contentTypeKey
          in: path
          description: The content type key
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                page:
                  type: integer
                  description: Page number (1-based)
                pageSize:
                  type: integer
                  description: Number of items per page
                filter:
                  type: string
                  description: Filter tree
                order:
                  type: string
                  description: Sorting configuration
                locale:
                  type: string
                  description: Locale code
                includeRelations:
                  type: array
                  description: Relation field keys to expand
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    description: Array of draft content items
                  total:
                    type: integer
                    description: Total matching items
                  page:
                    type: integer
                    description: Current page
                  pageSize:
                    type: integer
                    description: Items per page
                  totalPages:
                    type: integer
                    description: Total pages
                  hasMorePages:
                    type: boolean
                    description: Whether more pages exist
        '401':
          description: Unauthorized
      security:
        - ApiKey: [ ]
          Bearer: [ ]
    put:
      tags:
        - Preview Content (V1)
      summary: Create or update preview content
      description: Create a new draft content item or update an existing one.
      operationId: PreviewContents_CreateOrUpdate
      parameters:
        - name: contentTypeKey
          in: path
          description: The content type key
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: Content item ID. Null to create.
                contentType:
                  type: string
                  description: Content type key
                fields:
                  type: array
                  description: Array of typed fields
                clientInfo:
                  type: string
                  description: Optional client identifier
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Content item ID
                  contentType:
                    type: string
                    description: Content type key
                  fields:
                    type: array
                    description: Typed fields
        '401':
          description: Unauthorized
      security:
        - ApiKey: [ ]
          Bearer: [ ]
  '/preview-contents/{contentTypeKey}/ids':
    post:
      tags:
        - Preview Content (V1)
      summary: Get preview content IDs only
      description: Returns only the IDs of matching draft/preview content items.
      operationId: PreviewContents_GetIds
      parameters:
        - name: contentTypeKey
          in: path
          description: The content type key
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                filter:
                  type: string
                  description: Filter tree
                page:
                  type: integer
                  description: Page number
                pageSize:
                  type: integer
                  description: Items per page
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  ids:
                    type: array
                    description: Array of content item IDs
                  total:
                    type: integer
                    description: Total matching items
        '401':
          description: Unauthorized
      security:
        - ApiKey: [ ]
          Bearer: [ ]
  '/preview-contents/{contentTypeKey}/{id}':
    get:
      tags:
        - Preview Content (V1)
      summary: Get single preview content
      description: Retrieve a single draft/preview content item by its ID.
      operationId: PreviewContents_GetById
      parameters:
        - name: contentTypeKey
          in: path
          description: The content type key
          required: true
          schema:
            type: string
        - name: id
          in: path
          description: The content item ID (GUID)
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Content item ID
                  contentType:
                    type: string
                    description: Content type key
                  fields:
                    type: array
                    description: Array of typed fields
        '401':
          description: Unauthorized
        '404':
          description: Not Found
      security:
        - ApiKey: [ ]
          Bearer: [ ]
    post:
      tags:
        - Preview Content (V1)
      summary: Get preview content with relations
      description: Retrieve a draft/preview content item with expanded relations and locale.
      operationId: PreviewContents_GetWithRelations
      parameters:
        - name: contentTypeKey
          in: path
          description: The content type key
          required: true
          schema:
            type: string
        - name: id
          in: path
          description: The content item ID (GUID)
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                locale:
                  type: string
                  description: Locale code
                includeRelations:
                  type: array
                  description: Relation field keys to expand
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Content item ID
                  contentType:
                    type: string
                    description: Content type key
                  fields:
                    type: array
                    description: Array of typed fields with relations expanded
        '401':
          description: Unauthorized
        '404':
          description: Not Found
      security:
        - ApiKey: [ ]
          Bearer: [ ]
    delete:
      tags:
        - Preview Content (V1)
      summary: Delete preview content
      description: Permanently delete a draft/preview content item.
      operationId: PreviewContents_Delete
      parameters:
        - name: contentTypeKey
          in: path
          description: The content type key
          required: true
          schema:
            type: string
        - name: id
          in: path
          description: The content item ID (GUID)
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success — content deleted
        '401':
          description: Unauthorized
        '404':
          description: Not Found
      security:
        - ApiKey: [ ]
          Bearer: [ ]
  '/preview-contents/{contentTypeKey}/aggregate':
    post:
      tags:
        - Preview Content (V1)
      summary: Aggregate preview content field values
      description: Compute an aggregate on a field across matching draft/preview content items.
      operationId: PreviewContents_Aggregate
      parameters:
        - name: contentTypeKey
          in: path
          description: The content type key
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                fieldKey:
                  type: string
                  description: The field key to aggregate on
                aggregateType:
                  type: string
                  description: 'Sum, Avg, Min, Max, or Count'
                filter:
                  type: string
                  description: Optional filter
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  value:
                    type: number
                    description: Computed aggregate value
        '401':
          description: Unauthorized
      security:
        - ApiKey: [ ]
          Bearer: [ ]
  '/preview-contents/{contentTypeKey}/aggregategroup':
    post:
      tags:
        - Preview Content (V1)
      summary: Grouped aggregation on preview content
      description: Compute an aggregate grouped by a field across matching draft/preview content items.
      operationId: PreviewContents_AggregateGroup
      parameters:
        - name: contentTypeKey
          in: path
          description: The content type key
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                fieldKey:
                  type: string
                  description: The field key to aggregate on
                aggregateType:
                  type: string
                  description: 'Sum, Avg, Min, Max, or Count'
                groupByFieldKey:
                  type: string
                  description: The field key to group by
                filter:
                  type: string
                  description: Optional filter
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    description: Array of group-value / aggregate-value pairs
        '401':
          description: Unauthorized
      security:
        - ApiKey: [ ]
          Bearer: [ ]
  '/preview-contents/{contentTypeKey}/{id}/publish':
    put:
      tags:
        - Preview Content (V1)
      summary: Publish draft content
      description: 'Publish a draft/preview content item, making it available via the published content endpoints.'
      operationId: PreviewContents_Publish
      parameters:
        - name: contentTypeKey
          in: path
          description: The content type key
          required: true
          schema:
            type: string
        - name: id
          in: path
          description: The content item ID (GUID)
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                clientInfo:
                  type: string
                  description: Optional client identifier for audit logging
        required: true
      responses:
        '200':
          description: Success — content published
        '401':
          description: Unauthorized
        '404':
          description: Not Found
      security:
        - ApiKey: [ ]
          Bearer: [ ]
  '/preview-contents/{contentTypeKey}/{id}/unpublish':
    put:
      tags:
        - Preview Content (V1)
      summary: Unpublish content
      description: 'Unpublish a content item, reverting it to draft-only status and removing it from published content endpoints.'
      operationId: PreviewContents_Unpublish
      parameters:
        - name: contentTypeKey
          in: path
          description: The content type key
          required: true
          schema:
            type: string
        - name: id
          in: path
          description: The content item ID (GUID)
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                clientInfo:
                  type: string
                  description: Optional client identifier for audit logging
        required: true
      responses:
        '200':
          description: Success — content unpublished
        '401':
          description: Unauthorized
        '404':
          description: Not Found
      security:
        - ApiKey: [ ]
          Bearer: [ ]
  '/v2/preview-contents/{contentTypeKey}':
    post:
      tags:
        - Preview Content (V2)
      summary: Search preview contents (V2)
      description: Search draft/preview content items using the V2 flat-dictionary model.
      operationId: PreviewContentsV2_Search
      parameters:
        - name: contentTypeKey
          in: path
          description: The content type key
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                page:
                  type: integer
                  description: Page number (1-based)
                pageSize:
                  type: integer
                  description: Items per page
                filter:
                  type: string
                  description: Filter tree
                order:
                  type: string
                  description: Sorting configuration
                locale:
                  type: string
                  description: Locale code
                includeRelations:
                  type: array
                  description: Relation field keys to expand
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    description: Array of V2 draft content items
                  total:
                    type: integer
                    description: Total matching items
                  page:
                    type: integer
                    description: Current page
                  pageSize:
                    type: integer
                    description: Items per page
                  totalPages:
                    type: integer
                    description: Total pages
                  hasMorePages:
                    type: boolean
                    description: Whether more pages exist
        '401':
          description: Unauthorized
      security:
        - ApiKey: [ ]
          Bearer: [ ]
    put:
      tags:
        - Preview Content (V2)
      summary: Create or update preview content (V2)
      description: Create or update a draft content item using the V2 flat-dictionary model.
      operationId: PreviewContentsV2_CreateOrUpdate
      parameters:
        - name: contentTypeKey
          in: path
          description: The content type key
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: Content item ID. Omit to create.
                fields:
                  type: string
                  description: Flat dictionary of field key to value
                translations:
                  type: string
                  description: Translations dictionary
                clientInfo:
                  type: string
                  description: Optional client identifier
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Content item ID
                  fields:
                    type: string
                    description: Flat field dictionary
                  translations:
                    type: string
                    description: Translations dictionary
        '401':
          description: Unauthorized
      security:
        - ApiKey: [ ]
          Bearer: [ ]
  '/v2/preview-contents/{contentTypeKey}/ids':
    post:
      tags:
        - Preview Content (V2)
      summary: Get preview content IDs only (V2)
      description: Returns only the IDs of matching draft/preview content items.
      operationId: PreviewContentsV2_GetIds
      parameters:
        - name: contentTypeKey
          in: path
          description: The content type key
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                filter:
                  type: string
                  description: Filter tree
                page:
                  type: integer
                  description: Page number
                pageSize:
                  type: integer
                  description: Items per page
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  ids:
                    type: array
                    description: Array of content item IDs
                  total:
                    type: integer
                    description: Total matching items
        '401':
          description: Unauthorized
      security:
        - ApiKey: [ ]
          Bearer: [ ]
  '/v2/preview-contents/{contentTypeKey}/{id}':
    get:
      tags:
        - Preview Content (V2)
      summary: Get single preview content (V2)
      description: Retrieve a single draft/preview content item using the V2 model.
      operationId: PreviewContentsV2_GetById
      parameters:
        - name: contentTypeKey
          in: path
          description: The content type key
          required: true
          schema:
            type: string
        - name: id
          in: path
          description: The content item ID (GUID)
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Content item ID
                  fields:
                    type: string
                    description: Flat dictionary of field key to value
                  translations:
                    type: string
                    description: Dictionary of field key to locale-value pairs
        '401':
          description: Unauthorized
        '404':
          description: Not Found
      security:
        - ApiKey: [ ]
          Bearer: [ ]
  /assets:
    post:
      tags:
        - Assets
      summary: Search assets
      description: 'Search and filter digital assets with pagination, text search, date filtering, and type filtering.'
      operationId: Assets_Search
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                page:
                  type: integer
                  description: Page number (1-based)
                pageSize:
                  type: integer
                  description: Number of items per page
                search:
                  type: string
                  description: Free-text search across title and description
                since:
                  type: string
                  description: Only return assets updated after this timestamp
                filterByIds:
                  type: array
                  description: Restrict results to specific asset IDs
                contentTypes:
                  type: array
                  description: Filter by MIME content types (e.g. 'image/png')
                assetTypes:
                  type: array
                  description: 'Filter by asset type classifications (e.g. ''Image'', ''Document'')'
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    description: Array of asset items
                  total:
                    type: integer
                    description: Total matching assets
                  page:
                    type: integer
                    description: Current page
                  pageSize:
                    type: integer
                    description: Items per page
        '401':
          description: Unauthorized
      security:
        - ApiKey: [ ]
          Bearer: [ ]
  '/assets/{id}':
    get:
      tags:
        - Assets
      summary: Get single asset
      description: 'Retrieve a single asset by its ID, including metadata and file information.'
      operationId: Assets_GetById
      parameters:
        - name: id
          in: path
          description: The asset ID (GUID)
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Asset ID
                  title:
                    type: string
                    description: Asset title
                  description:
                    type: string
                    description: Asset description
                  fileInfo:
                    type: string
                    description: File metadata
                  assetType:
                    type: string
                    description: Asset type classification
                  lastUpdate:
                    type: string
                    description: Last update timestamp
        '401':
          description: Unauthorized
        '404':
          description: Not Found
      security:
        - ApiKey: [ ]
          Bearer: [ ]
    put:
      tags:
        - Assets
      summary: Update asset metadata
      description: Update the title and description of an existing asset without replacing the file.
      operationId: Assets_UpdateMetadata
      parameters:
        - name: id
          in: path
          description: The asset ID (GUID)
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                  description: New title for the asset
                description:
                  type: string
                  description: New description for the asset
        required: true
      responses:
        '200':
          description: Success — metadata updated
        '401':
          description: Unauthorized
        '404':
          description: Not Found
      security:
        - ApiKey: [ ]
          Bearer: [ ]
    delete:
      tags:
        - Assets
      summary: Delete asset
      description: Permanently delete an asset and its associated file.
      operationId: Assets_Delete
      parameters:
        - name: id
          in: path
          description: The asset ID (GUID)
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success — asset deleted
        '401':
          description: Unauthorized
        '404':
          description: Not Found
      security:
        - ApiKey: [ ]
          Bearer: [ ]
  /assets/getByHash:
    post:
      tags:
        - Assets
      summary: Find asset by MD5 hash
      description: Look up an existing asset by its MD5 hash and file size. Useful to detect duplicates before uploading.
      operationId: Assets_GetByHash
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                hash:
                  type: string
                  description: MD5 hash of the file content
                size:
                  type: string
                  description: File size in bytes
        required: true
      responses:
        '200':
          description: Success — returns matching asset or null
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Asset ID
                  title:
                    type: string
                    description: Asset title
                  fileInfo:
                    type: string
                    description: File metadata
        '401':
          description: Unauthorized
        '404':
          description: Not Found — no asset with matching hash and size
      security:
        - ApiKey: [ ]
          Bearer: [ ]
  /assets/upload:
    post:
      tags:
        - Assets
      summary: Upload file
      description: Upload a new file as an asset. Uses multipart/form-data encoding. Optionally checks MD5 to prevent duplicates.
      operationId: Assets_Upload
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                inputFile:
                  type: string
                  description: The file to upload
                fileName:
                  type: string
                  description: Desired file name for the asset
                title:
                  type: string
                  description: Title for the asset
                description:
                  type: string
                  description: Description for the asset
                checkMd5BeforeSend:
                  type: boolean
                  description: 'If true, check for duplicate by MD5 before storing'
        required: true
      responses:
        '200':
          description: Success — returns the created asset
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: New asset ID
                  title:
                    type: string
                    description: Asset title
                  fileInfo:
                    type: string
                    description: File metadata
                  assetType:
                    type: string
                    description: Detected asset type
        '401':
          description: Unauthorized
      security:
        - ApiKey: [ ]
          Bearer: [ ]
  /assets/upload-chunk:
    post:
      tags:
        - Assets
      summary: Chunked upload
      description: Upload a file in chunks for large files. Each chunk is uploaded individually and assembled server-side.
      operationId: Assets_UploadChunk
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                originalFileName:
                  type: string
                  description: The original file name
                fileUploadId:
                  type: string
                  description: A unique identifier for this upload session (GUID)
                chunkIndex:
                  type: integer
                  description: Zero-based index of this chunk
                chunkSize:
                  type: string
                  description: Size of this chunk in bytes
                totalChunkCount:
                  type: integer
                  description: Total number of chunks for the complete file
                stream:
                  type: string
                  description: The chunk binary data
        required: true
      responses:
        '200':
          description: 'Success — chunk received. When the last chunk is uploaded, the asset is assembled and returned.'
        '401':
          description: Unauthorized
      security:
        - ApiKey: [ ]
          Bearer: [ ]
  '/images/{assetId}':
    get:
      tags:
        - Images
      summary: Get or resize image
      description: 'Retrieve an image asset, optionally resized on-the-fly by specifying width, height, and quality parameters. Returns binary image data.'
      operationId: Images_GetById
      parameters:
        - name: assetId
          in: path
          description: The asset ID (GUID) of the image
          required: true
          schema:
            type: string
        - name: width
          in: query
          description: Desired width in pixels. Omit to preserve original width.
          schema:
            type: integer
        - name: height
          in: query
          description: Desired height in pixels. Omit to preserve original height.
          schema:
            type: integer
        - name: quality
          in: query
          description: JPEG/WebP quality (1-100). Default is original quality.
          schema:
            type: integer
      responses:
        '200':
          description: Success — binary image data (FileStreamResult)
          content:
            application/json:
              schema:
                type: object
                properties:
                  (binary):
                    type: string
                    description: Raw image bytes
        '401':
          description: Unauthorized
        '404':
          description: Not Found — asset does not exist or is not an image
      security:
        - ApiKey: [ ]
          Bearer: [ ]
  '/images/bypath/{path}':
    get:
      tags:
        - Images
      summary: Get image by path
      description: 'Retrieve an image asset by its storage path, optionally resized on-the-fly. Returns binary image data.'
      operationId: Images_GetByPath
      parameters:
        - name: path
          in: path
          description: The storage path of the image (e.g. 'products/hero-banner.jpg')
          required: true
          schema:
            type: string
        - name: width
          in: query
          description: Desired width in pixels
          schema:
            type: integer
        - name: height
          in: query
          description: Desired height in pixels
          schema:
            type: integer
        - name: quality
          in: query
          description: JPEG/WebP quality (1-100)
          schema:
            type: integer
      responses:
        '200':
          description: Success — binary image data (FileStreamResult)
          content:
            application/json:
              schema:
                type: object
                properties:
                  (binary):
                    type: string
                    description: Raw image bytes
        '401':
          description: Unauthorized
        '404':
          description: Not Found
      security:
        - ApiKey: [ ]
          Bearer: [ ]
  /content-types:
    get:
      tags:
        - Content Types
      summary: List all content types
      description: 'Retrieve all content type definitions in the workspace, including their field schemas.'
      operationId: ContentTypes_GetAll
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  (array):
                    type: array
                    description: Array of content type definitions
        '401':
          description: Unauthorized
      security:
        - ApiKey: [ ]
          Bearer: [ ]
    put:
      tags:
        - Content Types
      summary: Create or update content type
      description: Create a new content type definition or update an existing one. Include the full field schema in the request.
      operationId: ContentTypes_CreateOrUpdate
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: Content type ID. Null or omit to create.
                name:
                  type: string
                  description: Display name
                key:
                  type: string
                  description: 'Unique key (alphanumeric, PascalCase recommended)'
                icon:
                  type: string
                  description: Material icon name
                groupName:
                  type: string
                  description: Logical group name for organization
                fieldTitleKey:
                  type: string
                  description: Field key to use as display title in lists
                sortIndex:
                  type: integer
                  description: Sort order among content types
                versioningDisabled:
                  type: boolean
                  description: Whether to disable versioning for this type
                fields:
                  type: array
                  description: Array of field definitions
        required: true
      responses:
        '200':
          description: Success — returns the saved content type
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Content type ID
                  name:
                    type: string
                    description: Display name
                  key:
                    type: string
                    description: Unique key
                  fields:
                    type: array
                    description: Field definitions
        '401':
          description: Unauthorized
      security:
        - ApiKey: [ ]
          Bearer: [ ]
  '/content-types/{key}':
    get:
      tags:
        - Content Types
      summary: Get single content type
      description: Retrieve a single content type definition by its key.
      operationId: ContentTypes_GetByKey
      parameters:
        - name: key
          in: path
          description: 'The content type key (e.g. ''Article'', ''Product'')'
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Content type ID
                  name:
                    type: string
                    description: Display name
                  key:
                    type: string
                    description: Unique key
                  icon:
                    type: string
                    description: Material icon name
                  groupName:
                    type: string
                    description: Logical group name
                  fieldTitleKey:
                    type: string
                    description: Field key used as display title
                  sortIndex:
                    type: integer
                    description: Sort order
                  versioningDisabled:
                    type: boolean
                    description: Whether versioning is disabled
                  fields:
                    type: array
                    description: Array of field definitions
        '401':
          description: Unauthorized
        '404':
          description: Not Found
      security:
        - ApiKey: [ ]
          Bearer: [ ]
    delete:
      tags:
        - Content Types
      summary: Delete content type
      description: Delete a content type definition. The content type must have no existing content items (must be empty).
      operationId: ContentTypes_Delete
      parameters:
        - name: key
          in: path
          description: The content type key to delete
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success — content type deleted
        '401':
          description: Unauthorized
        '404':
          description: Not Found
        '409':
          description: Conflict — content type has existing content items
      security:
        - ApiKey: [ ]
          Bearer: [ ]
  /locales:
    get:
      tags:
        - Locales
      summary: Get all locales
      description: 'Retrieve all configured locales for the workspace, including fallback chains and the default locale.'
      operationId: Locales_GetAll
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  (array):
                    type: array
                    description: Array of locale configurations
        '401':
          description: Unauthorized
      security:
        - ApiKey: [ ]
          Bearer: [ ]
  /apps:
    get:
      tags:
        - Apps
      summary: Get app settings
      description: Retrieve the current app configuration including parameters and field mappings.
      operationId: Apps_GetSettings
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  parameters:
                    type: string
                    description: Dictionary of app parameter key-value pairs
                  fieldMapping:
                    type: string
                    description: Dictionary of field mapping configurations
        '401':
          description: Unauthorized
      security:
        - ApiKey: [ ]
          Bearer: [ ]
    post:
      tags:
        - Apps
      summary: Update app parameters
      description: Update the app's configuration parameters. Sends a key-value dictionary that is merged with existing parameters.
      operationId: Apps_UpdateParameters
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                (key-value pairs):
                  type: string
                  description: Dictionary of parameter key-value pairs to set or update
        required: true
      responses:
        '200':
          description: Success — parameters updated
        '401':
          description: Unauthorized
      security:
        - ApiKey: [ ]
          Bearer: [ ]
  '/apps/{userId}/workspaces/{workspaceId}':
    get:
      tags:
        - Apps
      summary: Get app settings for user workspace
      description: Retrieve app settings scoped to a specific user and workspace combination.
      operationId: Apps_GetSettingsForUser
      parameters:
        - name: userId
          in: path
          description: The user ID
          required: true
          schema:
            type: string
        - name: workspaceId
          in: path
          description: The workspace ID
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  parameters:
                    type: string
                    description: App parameters for this user/workspace
                  fieldMapping:
                    type: string
                    description: Field mappings
        '401':
          description: Unauthorized
        '404':
          description: Not Found
      security:
        - ApiKey: [ ]
          Bearer: [ ]
  /apps/workspaces:
    get:
      tags:
        - Apps
      summary: Get workspaces with app installed
      description: Retrieve the list of workspaces where this app is installed.
      operationId: Apps_GetWorkspaces
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  (array):
                    type: array
                    description: Array of workspace information objects
        '401':
          description: Unauthorized
      security:
        - ApiKey: [ ]
          Bearer: [ ]
  /apps/workspaces/all:
    get:
      tags:
        - Apps
      summary: Get all installed workspaces
      description: 'Retrieve all workspaces where this app is installed, across all users.'
      operationId: Apps_GetAllWorkspaces
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  (array):
                    type: array
                    description: Array of all workspace information objects
        '401':
          description: Unauthorized
      security:
        - ApiKey: [ ]
          Bearer: [ ]
  '/actions/{contentTypeKey}/{contentId}/{actionId}/execute':
    get:
      tags:
        - Content Actions
      summary: Execute action
      description: Execute a custom action defined on a content type for a specific content item.
      operationId: Actions_Execute
      parameters:
        - name: contentTypeKey
          in: path
          description: The content type key
          required: true
          schema:
            type: string
        - name: contentId
          in: path
          description: The content item ID (GUID)
          required: true
          schema:
            type: string
        - name: actionId
          in: path
          description: The action identifier
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success — action executed
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    description: Action-specific result data
        '401':
          description: Unauthorized
        '404':
          description: Not Found — content or action does not exist
      security:
        - ApiKey: [ ]
          Bearer: [ ]
  '/actions/{contentTypeKey}/{contentId}/{actionId}/navigate':
    get:
      tags:
        - Content Actions
      summary: Get navigation URL
      description: 'Get a navigation URL for a custom action, typically used to redirect users to an external page or detail view.'
      operationId: Actions_Navigate
      parameters:
        - name: contentTypeKey
          in: path
          description: The content type key
          required: true
          schema:
            type: string
        - name: contentId
          in: path
          description: The content item ID (GUID)
          required: true
          schema:
            type: string
        - name: actionId
          in: path
          description: The action identifier
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success — returns a navigation URL
          content:
            application/json:
              schema:
                type: object
                properties:
                  url:
                    type: string
                    description: The navigation URL to redirect to
        '401':
          description: Unauthorized
        '404':
          description: Not Found
      security:
        - ApiKey: [ ]
          Bearer: [ ]
  /ai-assistant/thread:
    post:
      tags:
        - AI Assistant
      summary: Start AI thread
      description: Start a new AI assistant conversation thread or continue an existing one by providing a prompt.
      operationId: AiAssistant_StartThread
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                threadId:
                  type: string
                  description: 'Existing thread ID to continue, or null to start a new conversation'
                prompt:
                  type: string
                  description: The user's message or question
        required: true
      responses:
        '200':
          description: Success — returns thread and run identifiers
          content:
            application/json:
              schema:
                type: object
                properties:
                  threadId:
                    type: string
                    description: The thread ID (use for subsequent requests)
                  runId:
                    type: string
                    description: The run ID (use to check status)
        '401':
          description: Unauthorized
      security:
        - ApiKey: [ ]
          Bearer: [ ]
  '/ai-assistant/thread/{threadId}/run/{runId}/status':
    get:
      tags:
        - AI Assistant
      summary: Check AI run status
      description: Check the status of an AI assistant run. Poll this endpoint until the status is 'completed' or 'failed'.
      operationId: AiAssistant_CheckStatus
      parameters:
        - name: threadId
          in: path
          description: The thread ID returned from the start endpoint
          required: true
          schema:
            type: string
        - name: runId
          in: path
          description: The run ID returned from the start endpoint
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    description: 'Run status: ''completed'', ''in_progress'', or ''failed'''
        '401':
          description: Unauthorized
        '404':
          description: Not Found — thread or run does not exist
      security:
        - ApiKey: [ ]
          Bearer: [ ]
  '/ai-assistant/thread/{threadId}/response':
    get:
      tags:
        - AI Assistant
      summary: Get AI response
      description: Retrieve the AI assistant's response text for a completed thread run.
      operationId: AiAssistant_GetResponse
      parameters:
        - name: threadId
          in: path
          description: The thread ID
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: string
                    description: The AI assistant's response text
        '401':
          description: Unauthorized
        '404':
          description: Not Found
      security:
        - ApiKey: [ ]
          Bearer: [ ]
  '/shared-access/{workspaceId}/asset/{id}':
    get:
      tags:
        - Shared Access
      summary: Download asset anonymously
      description: Download an asset file without authentication using a shared access key. The key must be provided as a query parameter.
      operationId: SharedAccess_DownloadAsset
      parameters:
        - name: workspaceId
          in: path
          description: The workspace ID that owns the asset
          required: true
          schema:
            type: string
        - name: id
          in: path
          description: The asset ID (GUID)
          required: true
          schema:
            type: string
        - name: sharedAccessKey
          in: query
          description: The shared access key that grants anonymous access to this asset
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success — binary file data
          content:
            application/json:
              schema:
                type: object
                properties:
                  (binary):
                    type: string
                    description: Raw file bytes
        '403':
          description: Forbidden — invalid or expired shared access key
        '404':
          description: Not Found
      security:
        - ApiKey: [ ]
          Bearer: [ ]
  /utility/server-time:
    get:
      tags:
        - Utility
      summary: Get server time
      description: Returns the current server time as Unix timestamp in milliseconds. No authentication required.
      operationId: Utility_GetServerTime
      responses:
        '200':
          description: Success — Unix timestamp in milliseconds
          content:
            application/json:
              schema:
                type: object
                properties:
                  value:
                    type: string
                    description: Server time as Unix timestamp in milliseconds
      security:
        - ApiKey: [ ]
          Bearer: [ ]
  /connect/token:
    post:
      tags:
        - Authorization
      summary: Get OAuth2 access token
      description: 'OAuth2 token endpoint. Supports grant types: client_credentials, refresh_token, api_key, and authorization_code. Returns an access token for authenticating subsequent API calls.'
      operationId: Authorization_Token
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                grant_type:
                  type: string
                  description: 'OAuth2 grant type: ''client_credentials'', ''refresh_token'', ''api_key'', or ''authorization_code'''
                client_id:
                  type: string
                  description: The client ID (application ID)
                client_secret:
                  type: string
                  description: The client secret (required for client_credentials grant)
                refresh_token:
                  type: string
                  description: The refresh token (required for refresh_token grant)
                api_key:
                  type: string
                  description: The API key (required for api_key grant)
                code:
                  type: string
                  description: The authorization code (required for authorization_code grant)
                redirect_uri:
                  type: string
                  description: Redirect URI (required for authorization_code grant)
                scope:
                  type: string
                  description: Requested scopes (space-separated)
        required: true
      responses:
        '200':
          description: Success — returns access token
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token:
                    type: string
                    description: The bearer token for API authentication
                  token_type:
                    type: string
                    description: 'Token type, always ''Bearer'''
                  expires_in:
                    type: integer
                    description: Token lifetime in seconds
                  refresh_token:
                    type: string
                    description: Refresh token for obtaining new access tokens
        '400':
          description: Bad Request — invalid grant type or missing required parameters
        '401':
          description: Unauthorized — invalid client credentials
      security:
        - ApiKey: [ ]
          Bearer: [ ]
components:
  securitySchemes:
    ApiKey:
      type: apiKey
      description: API Key authentication
      name: X-Api-Key
      in: header
    Bearer:
      type: http
      description: OAuth2 Bearer token
      scheme: bearer
      bearerFormat: JWT