Acoustic

Acoustic Authoring comments API

Use the Content Authoring comment APIs to work with comments. Comments are a simple way to associate a message to an item in Content. Comments are associated with a single item and user (creatorId). An item can have many comments. You can create, retrieve, and delete comments from a database.

Documentation GitHub OpenAPI

Operations 6

POST /authoring/v1/comments Create a comment.

GET /authoring/v1/comments/{id} Retrieve an existing comment.

PUT /authoring/v1/comments/{id} Update an existing comment.

DELETE /authoring/v1/comments/{id} Delete an existing comment.

GET /authoring/v1/comments/by-item/{classification}/{id} Retrieve all comments for a specific item.

GET /authoring/v1/comments/by-user/{userId} Retrieve all comments that were created by a user.

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this

find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/acoustic-authoring-comments-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no email required.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.2.0
info:
  title: Acoustic Authoring comments API
  version: 1.0.142
  x-ibm-name: ibm-watson-content-hub-api
  description: 'Operations tagged Authoring comments 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 comments
  description: Use the Content Authoring comment APIs to work with comments. Comments are a simple way to associate a message to an item in Content. Comments are associated with a single item and user (creatorId). An item can have many comments. You can create, retrieve, and delete comments from a database.
paths:
  /authoring/v1/comments:
    post:
      tags:
      - Authoring comments
      summary: Create a comment.
      description: 'Use the /comments endpoint to create a comment. You must provide a message and a target to create the comment.<br />User roles: admin, manager, editor'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                message:
                  type: string
                  description: The actual comment message.
                  example: More images should be added to slideshow
                target:
                  type: object
                  properties:
                    id:
                      type: string
                      description: The id of the item that the comment is associated with.
                      example: 6eac5498-3545-458a-962b-e17742aa7b56
                    classification:
                      type: string
                      description: The classification of the item that the comment is associated with.
                      enum:
                      - asset
                      - content
                      example: content
                  required:
                  - id
                  - classification
              required:
              - message
              - target
        description: Provide the comment message and target to create a comment.
        required: true
      responses:
        '201':
          description: Successfully created a comment for an item.
          content:
            application/json:
              schema:
                type: object
                properties:
                  creatorId:
                    type: string
                    description: The ID of the user that created the commment.
                    example: f8c1344e-2296-441b-a8a6-f8d46b72a787
                  id:
                    type: string
                    description: The id of the comment.
                    example: 95927bcd-9da3-4d8a-9fbf-ffcabe80a8a4
                  rev:
                    type: string
                    description: The revision of the comment.
                    example: 2-c839bbb8844549c2e298275c4b2adcb8
                  message:
                    type: string
                    description: The actual comment message.
                    example: More images should be added to slideshow
                  created:
                    type: string
                    format: date-time
                    description: ISO-8601 formatted date.
                    example: '2017-05-28T22:59:27.610Z'
                  target:
                    type: object
                    properties:
                      id:
                        type: string
                        description: The id of the item that the comment is associated with.
                        example: 6eac5498-3545-458a-962b-e17742aa7b56
                      classification:
                        type: string
                        description: The classification of the item that the comment is associated with.
                        enum:
                        - asset
                        - content
                        example: content
                    required:
                    - id
                    - classification
                  threadId:
                    type: string
                    description: The id string of the thread that this comment belongs to.
                    example: b3a18c87-8be0-4938-bba9-98a4cea35200
                  classification:
                    type: string
                    description: The comment's classification.
                    example: Comment
                  kind:
                    type: array
                    description: The "kind" of comment that this is. By default, all comments created by users are "user" comments.
                    default:
                    - user
                    items:
                      type: string
                      enum:
                      - user
                      - system
                  creator:
                    type: string
                    description: Display name of the user who created this comment.
                    example: Krista
                  lastModifier:
                    type: string
                    description: The display name of the user who last edited the comment.
                    example: Krista
                  lastModifierId:
                    type: string
                    description: The ID of the user who last edited the comment.
                    example: f8c1344e-2296-441b-a8a6-f8d46b72a787
                  lastModified:
                    type: string
                    description: The ISO-8601 timestamp that the comment was last modified.
                    example: '2017-05-28T22:59:27.610Z'
                  resolved:
                    type: boolean
                    default: false
                    description: Used for resolving comments during a review. This property is false by default and changes to true when the comment is resolved.
                required:
                - id
                - rev
                - classification
                - created
                - creator
                - creatorId
                - kind
                - lastModified
                - lastModifier
                - lastModifierId
                - message
                - resolved
                - target
                - threadId
        '400':
          description: The required parameters are missing or invalid. Provide valid parameters to create a comment.
          content:
            application/json:
              schema:
                type: object
                description: An error response.
                properties:
                  requestId:
                    type: string
                    description: The current request ID
                    example: d64dc285-0b62-aaa3-841f-de3588b64d34
                  service:
                    type: string
                    description: The name of the service that produced the error
                    example: authoring-resource
                  requestMethod:
                    type: string
                    description: The Http method type of the current request
                    example: GET
                  requestUri:
                    type: string
                    description: The request uri
                    example: /authoring/v1/comments
                  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
                          example: error.comments.1000
                        message:
                          type: string
                          description: The error message
                          example: The id requested does not exist.
                        description:
                          type: string
                          description: Optional detailed error message
                          example: Please check the ID you provided is correct before retrying the request.
                        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.
                        locale:
                          type: string
                          description: The current locale used to produce the error message.
                          example: en
                      required:
                      - code
                      - key
                      - message
                      - description
                      - category
                      - level
                      - parameters
                      - 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'
        '503':
          description: Unable to create the comment as the service is unavailable. Try again later.
          content:
            application/json:
              schema:
                type: object
                description: An error response.
                properties:
                  requestId:
                    type: string
                    description: The current request ID
                    example: d64dc285-0b62-aaa3-841f-de3588b64d34
                  service:
                    type: string
                    description: The name of the service that produced the error
                    example: authoring-resource
                  requestMethod:
                    type: string
                    description: The Http method type of the current request
                    example: GET
                  requestUri:
                    type: string
                    description: The request uri
                    example: /authoring/v1/comments
                  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
                          example: error.comments.1000
                        message:
                          type: string
                          description: The error message
                          example: The id requested does not exist.
                        description:
                          type: string
                          description: Optional detailed error message
                          example: Please check the ID you provided is correct before retrying the request.
                        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.
                        locale:
                          type: string
                          description: The current locale used to produce the error message.
                          example: en
                      required:
                      - code
                      - key
                      - message
                      - description
                      - category
                      - level
                      - parameters
                      - locale
                required:
                - requestId
                - service
                - requestMethod
                - requestUri
                - errors
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                type: object
                description: An error response.
                properties:
                  requestId:
                    type: string
                    description: The current request ID
                    example: d64dc285-0b62-aaa3-841f-de3588b64d34
                  service:
                    type: string
                    description: The name of the service that produced the error
                    example: authoring-resource
                  requestMethod:
                    type: string
                    description: The Http method type of the current request
                    example: GET
                  requestUri:
                    type: string
                    description: The request uri
                    example: /authoring/v1/comments
                  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
                          example: error.comments.1000
                        message:
                          type: string
                          description: The error message
                          example: The id requested does not exist.
                        description:
                          type: string
                          description: Optional detailed error message
                          example: Please check the ID you provided is correct before retrying the request.
                        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.
                        locale:
                          type: string
                          description: The current locale used to produce the error message.
                          example: en
                      required:
                      - code
                      - key
                      - message
                      - description
                      - category
                      - level
                      - parameters
                      - locale
                required:
                - requestId
                - service
                - requestMethod
                - requestUri
                - errors
      x-ibm-dx-security-user-roles:
      - admin
      - manager
      - editor
  /authoring/v1/comments/{id}:
    get:
      tags:
      - Authoring comments
      summary: Retrieve an existing comment.
      description: 'Use the /comments/{id} endpoint to retrieve an existing comment that matches the ID that is specified from the database.<br />User roles: admin, manager, editor, viewer'
      parameters:
      - name: id
        in: path
        description: Provide the ID of the comment that you want to retrieve.
        required: true
        schema:
          type: string
      - name: fields
        in: query
        description: Only the comment properties that are specified here are returned for each result. Any comment property is a valid value and can be specified in a comma-separated list. For example, to show only the comment properties message and creatorId, provide the values of message and creatorId. All comment properties are returned by default.
        required: false
        allowEmptyValue: true
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: Successfully retrieved the comment that matches the ID you specified.
          content:
            application/json:
              schema:
                type: object
                properties:
                  creatorId:
                    type: string
                    description: The ID of the user that created the commment.
                    example: f8c1344e-2296-441b-a8a6-f8d46b72a787
                  id:
                    type: string
                    description: The id of the comment.
                    example: 95927bcd-9da3-4d8a-9fbf-ffcabe80a8a4
                  rev:
                    type: string
                    description: The revision of the comment.
                    example: 2-c839bbb8844549c2e298275c4b2adcb8
                  message:
                    type: string
                    description: The actual comment message.
                    example: More images should be added to slideshow
                  created:
                    type: string
                    format: date-time
                    description: ISO-8601 formatted date.
                    example: '2017-05-28T22:59:27.610Z'
                  target:
                    type: object
                    properties:
                      id:
                        type: string
                        description: The id of the item that the comment is associated with.
                        example: 6eac5498-3545-458a-962b-e17742aa7b56
                      classification:
                        type: string
                        description: The classification of the item that the comment is associated with.
                        enum:
                        - asset
                        - content
                        example: content
                    required:
                    - id
                    - classification
                  threadId:
                    type: string
                    description: The id string of the thread that this comment belongs to.
                    example: b3a18c87-8be0-4938-bba9-98a4cea35200
                  classification:
                    type: string
                    description: The comment's classification.
                    example: Comment
                  kind:
                    type: array
                    description: The "kind" of comment that this is. By default, all comments created by users are "user" comments.
                    default:
                    - user
                    items:
                      type: string
                      enum:
                      - user
                      - system
                  creator:
                    type: string
                    description: Display name of the user who created this comment.
                    example: Krista
                  lastModifier:
                    type: string
                    description: The display name of the user who last edited the comment.
                    example: Krista
                  lastModifierId:
                    type: string
                    description: The ID of the user who last edited the comment.
                    example: f8c1344e-2296-441b-a8a6-f8d46b72a787
                  lastModified:
                    type: string
                    description: The ISO-8601 timestamp that the comment was last modified.
                    example: '2017-05-28T22:59:27.610Z'
                  resolved:
                    type: boolean
                    default: false
                    description: Used for resolving comments during a review. This property is false by default and changes to true when the comment is resolved.
                required:
                - id
                - rev
                - classification
                - created
                - creator
                - creatorId
                - kind
                - lastModified
                - lastModifier
                - lastModifierId
                - message
                - resolved
                - target
                - threadId
        '404':
          description: A comment that matches the ID you specified was not found.
          content:
            application/json:
              schema:
                type: object
                description: An error response.
                properties:
                  requestId:
                    type: string
                    description: The current request ID
                    example: d64dc285-0b62-aaa3-841f-de3588b64d34
                  service:
                    type: string
                    description: The name of the service that produced the error
                    example: authoring-resource
                  requestMethod:
                    type: string
                    description: The Http method type of the current request
                    example: GET
                  requestUri:
                    type: string
                    description: The request uri
                    example: /authoring/v1/comments
                  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
                          example: error.comments.1000
                        message:
                          type: string
                          description: The error message
                          example: The id requested does not exist.
                        description:
                          type: string
                          description: Optional detailed error message
                          example: Please check the ID you provided is correct before retrying the request.
                        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.
                        locale:
                          type: string
                          description: The current locale used to produce the error message.
                          example: en
                      required:
                      - code
                      - key
                      - message
                      - description
                      - category
                      - level
                      - parameters
                      - 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'
        '503':
          description: Unable to retrieve the comment from the database as the service is unavailable. Try again later.
          content:
            application/json:
              schema:
                type: object
                description: An error response.
                properties:
                  requestId:
                    type: string
                    description: The current request ID
                    example: d64dc285-0b62-aaa3-841f-de3588b64d34
                  service:
                    type: string
                    description: The name of the service that produced the error
                    example: authoring-resource
                  requestMethod:
                    type: string
                    description: The Http method type of the current request
                    example: GET
                  requestUri:
                    type: string
                    description: The request uri
                    example: /authoring/v1/comments
                  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
                          example: error.comments.1000
                        message:
                          type: string
                          description: The error message
                          example: The id requested does not exist.
                        description:
                          type: string
                          description: Optional detailed error message
                          example: Please check the ID you provided is correct before retrying the request.
                        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.
                        locale:
                          type: string
                          description: The current locale used to produce the error message.
                          example: en
                      required:
                      - code
                      - key
                      - message
                      - description
                      - category
                      - level
                      - parameters
                      - locale
                required:
                - requestId
                - service
                - requestMethod
                - requestUri
                - errors
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                type: object
                description: An error response.
                properties:
                  requestId:
                    type: string
                    description: The current request ID
                    example: d64dc285-0b62-aaa3-841f-de3588b64d34
                  service:
                    type: string
                    description: The name of the service that produced the error
                    example: authoring-resource
                  requestMethod:
                    type: string
                    description: The Http method type of the current request
                    example: GET
                  requestUri:
                    type: string
                    description: The request uri
                    example: /authoring/v1/comments
                  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
                          example: error.comments.1000
                        message:
                          type: string
                          description: The error message
                          example: The id requested does not exist.
                        description:
                          type: string
                          description: Optional detailed error message
                          example: Please check the ID you provided is correct before retrying the request.
                        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.
                        locale:
                          type: string
                          description: The current locale used to produce the error message.
                          example: en
                      required:
                      - code
                      - key
                      - message
                      - description
                      - category
                      - level
                      - parameters
                      - locale
                required:
                - requestId
                - service
                - requestMethod
                - requestUri
                - errors
      x-ibm-dx-security-user-roles:
      - admin
      - manager
      - editor
      - viewer
    put:
      tags:
      - Authoring comments
      summary: Update an existing comment.
      description: 'Use the /comments/{id} end point to update an existing comment that matches the ID that is specified.<br />User roles: admin, manager, editor'
      parameters:
      - name: id
   

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