Acoustic Authoring categories API

openapi: 3.2.0
info:
  title: Acoustic Authoring categories API
  version: 1.0.142
  x-ibm-name: ibm-watson-content-hub-api
  description: 'Operations tagged Authoring categories across 2 of this provider''s published API definitions: acoustic-content-openapi-original.json, acoustic-content-swagger2-original.yaml. Each path carries the servers of the definition it was published in.'
tags:
- name: Authoring categories
  description: Use the Acoustic Content category authoring data service Rest APIs to work with category and taxonomy items.
paths:
  /authoring/v1/categories:
    get:
      tags:
      - Authoring categories
      summary: Retrieve all the taxonomies.
      description: 'Retrieve all the taxonomies (root categories).<br />User roles: admin, manager, editor, viewer'
      parameters:
      - name: offset
        in: query
        description: Use the offset parameter to specify the number of content items to skip from the beginning of the list and return the rest.
        required: false
        schema:
          type: number
          format: integer
      - name: limit
        in: query
        description: Set the limit for the maximum number of content items to return in a single result. The default value is 50.
        required: false
        schema:
          type: number
          format: integer
      responses:
        '200':
          description: The taxonomies were successfully retrieved.
          content:
            application/json:
              schema:
                type: object
                properties:
                  limit:
                    type: integer
                    description: The page size.
                    example: 50
                  offset:
                    type: integer
                    description: The number of items to skip from the beginning of the list.
                    example: 0
                  href:
                    type: string
                    description: A link to the current page.
                    example: /authoring/v1/categories?offset=50&limit=50
                  next:
                    type: string
                    description: A link to the next page. Only shown if a next page exists.
                    example: /authoring/v1/categories?offset=100&limit=50
                  previous:
                    type: string
                    description: A link to the previous page. Only shown if a previous page exists.
                    example: /authoring/v1/categories?offset=0&limit=50
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: The ID of category.
                        rev:
                          type: string
                          description: The revision of category.
                        name:
                          type: string
                          description: The name of the category.
                        classification:
                          type: string
                          description: Either a Taxonomy or category.
                        description:
                          type: string
                          description: A written representation of the category.
                        creatorId:
                          type: string
                          description: The uuid of the user who created the category.
                        permanent:
                          type: boolean
                          description: Used to identify system categories, if true the category can not be deleted.
                        hidden:
                          type: boolean
                          description: If true the category is hidden in the Shell, value is not returned if false.  Default is false.
                        firstClassFor:
                          type: string
                          description: Array of item classifications to which this taxonomy is enabled.  Acceptable values "" and "imagesAndVideos", default "".  By default the taxonomy is only shown where generic selection of any category in any taxonomy is allowed.
                        parent:
                          type: string
                          description: The ID of the parent category. This is only required if the classification is a CATEGORY.
                        ancestorIds:
                          type: array
                          description: An array of IDs for each of the category's ancestor categories. The ID of this category is not included.
                          items:
                            type: string
                        namePath:
                          type: array
                          description: An array of names for each of the category's ancestor categories, in addition to the name of this category.
                          minItems: 1
                          items:
                            type: string
                        tags:
                          type: array
                          items:
                            type: string
                          uniqueItems: true
                          description: Array of tags. This field is applicable only for taxonomy.
                        links:
                          type: object
                          description: A set of links to related documents.
                          properties:
                            self:
                              type: object
                              properties:
                                href:
                                  type: string
                            taxonomy:
                              type: object
                              description: A link to this category's taxonomy. This will only be included if this category is not a taxonomy.
                              properties:
                                href:
                                  type: string
                            parent:
                              type: object
                              description: A link to this category's parent. This will only be included if this category is not a taxonomy.
                              properties:
                                href:
                                  type: string
                        lastModified:
                          type: string
                          format: date
                          description: When the category was last modified in ISO 8601 format.
                        created:
                          type: string
                          format: date
                          description: When the category was created in ISO 8601 format.
                      required:
                      - id
                      - rev
                      - name
                      - classification
                      - namePath
                      - links
                      - created
                      - lastModified
        '429':
          description: Too Many Requests, the server has reached a limit, the request must be sent again at a later time.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-ibm-dx-security-user-roles:
      - admin
      - manager
      - editor
      - viewer
    post:
      tags:
      - Authoring categories
      summary: Create a new category.
      description: 'Create a category with the contents of the JSON body.<br />User roles: admin, manager'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: The name of the category. It can contain any character except for a forward slash (/).
                parent:
                  type: string
                  description: The ID of the parent category. A taxonomy will be created if this is omitted.
                description:
                  type: string
                  description: The description of the category.
                permanent:
                  type: boolean
                  description: Used to identify system categories, if true the category can not be deleted.
                hidden:
                  type: boolean
                  description: If true the category is hidden in the Shell, value is not returned if false.  Default is false.
                firstClassFor:
                  type: string
                  description: Array of item classifications to which this taxonomy is enabled.  Acceptable values "" and "imagesAndVideos", default "".  By default the taxonomy is only shown where generic selection of any category in any taxonomy is allowed.
                tags:
                  type: array
                  items:
                    type: string
                  uniqueItems: true
                  description: Array of tags. This field is applicable only for taxonomy.
              required:
              - name
        description: The JSON data that is used to create the category.
        required: true
      responses:
        '201':
          description: The category was successfully created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: The ID of category.
                  rev:
                    type: string
                    description: The revision of category.
                  name:
                    type: string
                    description: The name of the category.
                  classification:
                    type: string
                    description: Either a Taxonomy or category.
                  description:
                    type: string
                    description: A written representation of the category.
                  creatorId:
                    type: string
                    description: The uuid of the user who created the category.
                  permanent:
                    type: boolean
                    description: Used to identify system categories, if true the category can not be deleted.
                  hidden:
                    type: boolean
                    description: If true the category is hidden in the Shell, value is not returned if false.  Default is false.
                  firstClassFor:
                    type: string
                    description: Array of item classifications to which this taxonomy is enabled.  Acceptable values "" and "imagesAndVideos", default "".  By default the taxonomy is only shown where generic selection of any category in any taxonomy is allowed.
                  parent:
                    type: string
                    description: The ID of the parent category. This is only required if the classification is a CATEGORY.
                  ancestorIds:
                    type: array
                    description: An array of IDs for each of the category's ancestor categories. The ID of this category is not included.
                    items:
                      type: string
                  namePath:
                    type: array
                    description: An array of names for each of the category's ancestor categories, in addition to the name of this category.
                    minItems: 1
                    items:
                      type: string
                  tags:
                    type: array
                    items:
                      type: string
                    uniqueItems: true
                    description: Array of tags. This field is applicable only for taxonomy.
                  links:
                    type: object
                    description: A set of links to related documents.
                    properties:
                      self:
                        type: object
                        properties:
                          href:
                            type: string
                      taxonomy:
                        type: object
                        description: A link to this category's taxonomy. This will only be included if this category is not a taxonomy.
                        properties:
                          href:
                            type: string
                      parent:
                        type: object
                        description: A link to this category's parent. This will only be included if this category is not a taxonomy.
                        properties:
                          href:
                            type: string
                  lastModified:
                    type: string
                    format: date
                    description: When the category was last modified in ISO 8601 format.
                  created:
                    type: string
                    format: date
                    description: When the category was created in ISO 8601 format.
                required:
                - id
                - rev
                - name
                - classification
                - namePath
                - links
                - created
                - lastModified
        '400':
          description: The JSON body is either missing fields, or contains invalid fields.
          content:
            application/json:
              schema:
                type: object
                description: an error response.
                properties:
                  requestId:
                    type: string
                    description: The current request ID
                  service:
                    type: string
                    description: The name of the service that produced the error
                  requestMethod:
                    type: string
                    description: The Http method type of the current request
                  requestUri:
                    type: string
                    description: The request uri
                  errors:
                    type: array
                    items:
                      type: object
                      description: an individual error, info or warning message.
                      properties:
                        code:
                          type: integer
                          description: The message code
                        key:
                          type: string
                          description: The message key
                        message:
                          type: string
                          description: The error message
                        description:
                          type: string
                          description: Optional detailed error message
                        more_info:
                          type: string
                          description: Optional additional information for the message
                        category:
                          type: string
                          description: The message category whereby only user messages are designed to be shown to an end user
                          enum:
                          - API
                          - USER
                        level:
                          type: string
                          description: Indicates the message level
                          enum:
                          - INFO
                          - WARNING
                          - ERROR
                        parameters:
                          type: object
                          description: The message parameters of this message.
                        field:
                          type: string
                          description: Only present on field validation errors, indicates the field in error.
                        locale:
                          type: string
                          description: The current locale used to produce the error message.
                      required:
                      - code
                      - key
                      - message
                      - description
                      - more_info
                      - category
                      - level
                      - parameters
                      - field
                      - locale
                required:
                - requestId
                - service
                - requestMethod
                - requestUri
                - errors
        '409':
          description: A category with the same path exists.
          content:
            application/json:
              schema:
                type: object
                description: an error response.
                properties:
                  requestId:
                    type: string
                    description: The current request ID
                  service:
                    type: string
                    description: The name of the service that produced the error
                  requestMethod:
                    type: string
                    description: The Http method type of the current request
                  requestUri:
                    type: string
                    description: The request uri
                  errors:
                    type: array
                    items:
                      type: object
                      description: an individual error, info or warning message.
                      properties:
                        code:
                          type: integer
                          description: The message code
                        key:
                          type: string
                          description: The message key
                        message:
                          type: string
                          description: The error message
                        description:
                          type: string
                          description: Optional detailed error message
                        more_info:
                          type: string
                          description: Optional additional information for the message
                        category:
                          type: string
                          description: The message category whereby only user messages are designed to be shown to an end user
                          enum:
                          - API
                          - USER
                        level:
                          type: string
                          description: Indicates the message level
                          enum:
                          - INFO
                          - WARNING
                          - ERROR
                        parameters:
                          type: object
                          description: The message parameters of this message.
                        field:
                          type: string
                          description: Only present on field validation errors, indicates the field in error.
                        locale:
                          type: string
                          description: The current locale used to produce the error message.
                      required:
                      - code
                      - key
                      - message
                      - description
                      - more_info
                      - category
                      - level
                      - parameters
                      - field
                      - locale
                required:
                - requestId
                - service
                - requestMethod
                - requestUri
                - errors
        '429':
          description: Too Many Requests, the server has reached a limit, the request must be sent again at a later time.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-ibm-dx-security-user-roles:
      - admin
      - manager
  /authoring/v1/categories/{id}:
    get:
      tags:
      - Authoring categories
      summary: Retrieve an existing category item.
      description: 'Retrieve the category with ID {id}.<br />User roles: admin, manager, editor, viewer'
      parameters:
      - name: id
        in: path
        required: true
        description: The ID of the category to retrieve.
        schema:
          type: string
      responses:
        '200':
          description: The category was successfully retrieved.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: The ID of category.
                  rev:
                    type: string
                    description: The revision of category.
                  name:
                    type: string
                    description: The name of the category.
                  classification:
                    type: string
                    description: Either a Taxonomy or category.
                  description:
                    type: string
                    description: A written representation of the category.
                  creatorId:
                    type: string
                    description: The uuid of the user who created the category.
                  permanent:
                    type: boolean
                    description: Used to identify system categories, if true the category can not be deleted.
                  hidden:
                    type: boolean
                    description: If true the category is hidden in the Shell, value is not returned if false.  Default is false.
                  firstClassFor:
                    type: string
                    description: Array of item classifications to which this taxonomy is enabled.  Acceptable values "" and "imagesAndVideos", default "".  By default the taxonomy is only shown where generic selection of any category in any taxonomy is allowed.
                  parent:
                    type: string
                    description: The ID of the parent category. This is only required if the classification is a CATEGORY.
                  ancestorIds:
                    type: array
                    description: An array of IDs for each of the category's ancestor categories. The ID of this category is not included.
                    items:
                      type: string
                  namePath:
                    type: array
                    description: An array of names for each of the category's ancestor categories, in addition to the name of this category.
                    minItems: 1
                    items:
                      type: string
                  tags:
                    type: array
                    items:
                      type: string
                    uniqueItems: true
                    description: Array of tags. This field is applicable only for taxonomy.
                  links:
                    type: object
                    description: A set of links to related documents.
                    properties:
                      self:
                        type: object
                        properties:
                          href:
                            type: string
                      taxonomy:
                        type: object
                        description: A link to this category's taxonomy. This will only be included if this category is not a taxonomy.
                        properties:
                          href:
                            type: string
                      parent:
                        type: object
                        description: A link to this category's parent. This will only be included if this category is not a taxonomy.
                        properties:
                          href:
                            type: string
                  lastModified:
                    type: string
                    format: date
                    description: When the category was last modified in ISO 8601 format.
                  created:
                    type: string
                    format: date
                    description: When the category was created in ISO 8601 format.
                required:
                - id
                - rev
                - name
                - classification
                - namePath
                - links
                - created
                - lastModified
        '404':
          description: The category with ID {id} was not found.
          content:
            application/json:
              schema:
                type: object
                description: an error response.
                properties:
                  requestId:
                    type: string
                    description: The current request ID
                  service:
                    type: string
                    description: The name of the service that produced the error
                  requestMethod:
                    type: string
                    description: The Http method type of the current request
                  requestUri:
                    type: string
                    description: The request uri
                  errors:
                    type: array
                    items:
                      type: object
                      description: an individual error, info or warning message.
                      properties:
                        code:
                          type: integer
                          description: The message code
                        key:
                          type: string
                          description: The message key
                        message:
                          type: string
                          description: The error message
                        description:
                          type: string
                          description: Optional detailed error message
                        more_info:
                          type: string
                          description: Optional additional information for the message
                        category:
                          type: string
                          description: The message category whereby only user messages are designed to be shown to an end user
                          enum:
                          - API
                          - USER
                        level:
                          type: string
                          description: Indicates the message level
                          enum:
                          - INFO
                          - WARNING
                          - ERROR
                        parameters:
                          type: object
                          description: The message parameters of this message.
                        field:
                          type: string
                          description: Only present on field validation errors, indicates the field in error.
                        locale:
                          type: string
                          description: The current locale used to produce the error message.
                      required:
                      - code
                      - key
                      - message
                      - description
                      - more_info
                      - category
                      - level
                      - parameters
                      - field
                      - locale
                required:
                - requestId
                - service
                - requestMethod
                - requestUri
                - errors
        '429':
          description: Too Many Requests, the server has reached a limit, the request must be sent again at a later time.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-ibm-dx-security-user-roles:
      - admin
      - manager
      - editor
      - viewer
    put:
      tags:
      - Authoring categories
      summary: Update an existing category item.
      description: 'Update the category with ID {id}.<br />User roles: admin, manager'
      parameters:
      - name: id
        in: path
        required: true
        description: The ID of the category to update.
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: The name of the category. It can contain any character except for a forward slash (/).
                parent:
                  type: string
                  description: The ID of the parent category. A taxonomy will be created if this is omitted.
                description:
                  type: string
                  description: The description of the category.
                permanent:
                  type: boolean
                  description: Used to identify system categories, if true the category can not be deleted.
                hidden:
                  type: boolean
                  description: If true the category is hidden in the Shell, value is not returned if false.  Default is false.
                firstClassFor:
                  type: string
                  description: Array of item classifications to which this taxonomy is enabled.  Acceptable values "" and "imagesAndVideos", default "".  By default the taxonomy is only shown where generic selection of any category in any taxonomy is allowed.
                tags:
                  type: array
                  items:
                    type: string
                  uniqueItems: true
                  description: Array of tags. This field is applicable only for taxonomy.
              required:
              - name
      responses:
        '200':
          description: The category was successfully updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: The ID of category.
                  rev:
                    type: string
                    description: The revision of category.
                  name:
                    type: string
                    description: The name of the category.
                  classification:
                    type: string
                    description: Either a Taxonomy or category.
                  description:
                    type: string
                    description: A written representation of the category.
                  creatorId:
                    type: string
                    description: The uuid of the user who created the category.
                  permanent:
                    type: boolean
                    description: Used to identify system categories, if true the category can not be deleted.
                  hidden:
                    type: boolean
                    description: If true the category is hidden in the Shell, value is not returned if false.  Default is false.
                  firstClassFor:
                    type: string
                    description: Array of item classifications to which this taxonomy is enabled.  Acceptable values "" and "imagesAndVideos", default "".  By default the taxonomy is only shown where generic selection of any category in any taxonomy is allowed.
                  parent:
                    type: string
                    description: The ID of the parent category. This is only required if the classification is a CATEGORY.
                  ancestorIds:
                    type: array
                    description: An array of IDs for each of the category's ancestor categories. The ID of this category is not included.
                    items:
                      type: string
           

# --- truncated at 32 KB (90 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/acoustic/refs/heads/main/openapi/acoustic-authoring-categories-api-openapi.yml