Acoustic Authoring content API
## General Use the Content content authoring data service Rest APIs to work with content documents. Content includes items that you compose in your content hub and upload from outside your content subscription. You can create, retrieve, and update content documents in a database. You can also create draft versions, change the status, and get a count of the total content in your database. ## Content workflow (status) The status of a content item can be determined by the **suffix** of the ID: - An ID like xxxx:**draft** indicates that the item is a draft. This is the initial status of a new content item until it is published. A draft of a published content item will also have this suffix. - An ID like xxxx:***[publishing_job_id]*** - indicates that the content item has been scheduled for publish in the given publishing job. - An ID like xxxx with no suffix indicates that the content is **published** or **retired**. A draft can be created from published. When such a draft is published, it will override the previously published content. **Key notes:** - The base ID (xxxx) does not change. Only the suffix changes according to the workflow status of the item. - Where content and assets are referenced from within a content item, the 'raw' ID form, without a suffix, is always used. For example, when a draft content item is referenced by another draft content item, the reference appears as a raw ID, and thus does not change when the items are published. - API clients should not depend on the ID format and should not attempt to parse it. Instead, the ***linkedDocId*** and ***links*** properties should be used. - Draft item have a property ***linkedDocId***. This is the Id that the draft item will have when it is published. - Draft items that have a published version will have a ***linkedDoc*** property within the ***links*** property. This property will not appear for drafts that do not have a published version.
GET
/authoring/v1/content
List all content items in the database.
POST
/authoring/v1/content
Create content items.
GET
/authoring/v1/content/{id}
Retrieve an existing content item.
PUT
/authoring/v1/content/{id}
Update an existing content item.
DELETE
/authoring/v1/content/{id}
Delete an existing content item immediately.
GET
/authoring/v1/content/views/by-type
Retrieve all content of the specified type.
GET
/authoring/v1/content/views/by-modified
Retrieve all content modified within the specified date.
POST
/authoring/v1/content/{id}/create-draft
Create a draft version of an existing content item.
GET
/authoring/v1/content/count
Retrieve the total number of content items in the database.
POST
/authoring/v1/content/{id}/analyze
AI analyzes and provides tag recommendations for the content.
POST
/authoring/v1/content/{id}/validate
Validate the specified content item against its type.
POST
/authoring/v1/content/{id}/unpublish
Unpublish a published item.
Documentation
Specifications
Other Resources
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-content-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.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Acoustic Authoring content API
version: 1.0.142
x-ibm-name: ibm-watson-content-hub-api
description: 'Operations tagged Authoring content 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 content
description: ' ## General
Use the Content content authoring data service Rest APIs to work with content documents. Content includes items that you compose in your content hub and upload from outside your content subscription. You can create, retrieve, and update content documents in a database. You can also create draft versions, change the status, and get a count of the total content in your database.
## Content workflow (status)
The status of a content item can be determined by the **suffix** of the ID:
- An ID like xxxx:**draft** indicates that the item is a draft. This is the initial status of a new content item until it is published. A draft of a published content item will also have this suffix.
- An ID like xxxx:***[publishing_job_id]*** - indicates that the content item has been scheduled for publish in the given publishing job.
- An ID like xxxx with no suffix indicates that the content is **published** or **retired**.
A draft can be created from published. When such a draft is published, it will override the previously published content.
**Key notes:**
- The base ID (xxxx) does not change. Only the suffix changes according to the workflow status of the item.
- Where content and assets are referenced from within a content item, the ''raw'' ID form, without a suffix, is always used. For example, when a draft content item is referenced by another draft content item, the reference appears as a raw ID, and thus does not change when the items are published.
- API clients should not depend on the ID format and should not attempt to parse it. Instead, the ***linkedDocId*** and ***links*** properties should be used.
- Draft item have a property ***linkedDocId***. This is the Id that the draft item will have when it is published.
- Draft items that have a published version will have a ***linkedDoc*** property within the ***links*** property. This property will not appear for drafts that do not have a published version.'
paths:
/authoring/v1/content:
get:
summary: List all content items in the database.
description: 'Use the /content endpoint to list all content items in the database.
<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: fields
in: query
description: Only the content items fields that are specified here are returned for each result. Any content item field is a valid value and can be specified as a comma-separated list. For example, to list the content item fields name and ID, provide the value ID, and name. All content item fields are returned by default.
required: false
schema:
type: string
- 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
tags:
- Authoring content
responses:
'200':
description: Successfully lists a paged result view of all content items in the database.
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/content?offset=50&limit=50
next:
type: string
description: A link to the next page. Only shown if a next page exists.
example: /authoring/v1/content?offset=100&limit=50
previous:
type: string
description: A link to the previous page. Only shown if a previous page exists.
example: /authoring/v1/content?offset=0&limit=50
items:
type: array
items:
title: Content Schema
type: object
properties:
id:
type: string
description: The ID of the content item.
example: 925d1454-167b-431b-a54c-6cbf0354398d
rev:
type: string
description: The current revision of the document.
example: 25-2ba981d0661c3129c31cc4993e569e3f
name:
type: string
description: The name of the content item.
example: Sample Content
description:
type: string
description: The description of the content item.
example: An example description of the sample content
typeId:
type: string
description: The ID of the content type this item belongs to.
example: b0798e67-3da2-48b4-b044-016495fa3ead
type:
type: string
description: The name of the content type this item belongs to. Only included when using include=metadata
example: Article
kind:
type: string
description: The kind of the content. Recognized values are "site", "page", "landing-page", "email"
example: email
lastModified:
type: string
format: date-time
description: The last modified date of this content item in ISO 8601 with the format YYYY-MM-DDTHH:mm:ss.sssZ. This field is read only.
example: '2016-11-02T06:28:47Z'
lastModifierId:
type: string
description: The ID of the user that last modified the content.
example: 63b800fa-51a7-4602-8cbe-ab3b9cee28b9
lastModifier:
type: string
description: The display name of the user that last modified the content.
example: Thomas Watson
created:
type: string
format: date-time
description: The created date of this content item in ISO 8601 with the format YYYY-MM-DDTHH:mm:ss.sssZ. This field is read only.
example: '2016-11-02T06:28:47Z'
creatorId:
type: string
description: The ID of the creator of the content.
example: 8c622bbb-5f5b-45d4-89e1-fce1c054138f
creator:
type: string
description: The display name of the user that created the content.
example: Thomas Watson
classification:
description: The classification defines the document type. For content items, all documents are classified as "content".
enum:
- content
status:
description: the workflow status of the content.
enum:
- draft
- ready
- retired
linkedDocId:
type: string
description: Provided on drafts of existing items. This is the ID of the primary item.
example: b289c02e-2c61-4643-aba6-e6b4e94c76e3
elements:
type: object
description: The elements section is dependent on the content type of this content. (Referenced via the typeId attribute) with Elements are defined in the content type and therefore the elements section is dependent on the content type of this content. The content type is referenced through the typeId attribute. A content can have multiple elements such as text, number, video, images etc. For a complete list of content elements see, https://developer.goacoustic.com/acoustic-content/reference#authoring-content
example:
videokey:
elementType: video
asset:
id: a21b3718-a801-4343-8a73-6f94ee2763ba
resourceUri: /authoring/v1/resources/438259a6a8ac72817ee2b2a14078c4a1
fileSize: 448338
fileName: testVideo.mp4
mediaType: video/mp4
thumbnail:
resourceId: ef2e1f5fa89f2f93dfba19520f629c84
resourceUri: /authoring/v1/resources/ef2e1f5fa89f2f93dfba19520f629c84
fileName: cap.jpg
categorykey:
elementType: category
categoryIds:
- ae607a10216249805ee0488d3e0f1e64
datekey:
elementType: datetime
value: '2016-11-07T10:09:00Z'
textkey:
elementType: text
value: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua
togglekey:
elementType: toggle
value: true
linkkey:
elementType: link
linkURL: http://acoustic.com
linkText: Acoustic
imagekey:
elementType: image
renditions:
default:
renditionId: 61096914-e33a-4021-9a5d-be06337206fd
source: /authoring/v1/resources/c45c83a8-2738-48a2-89e1-35256ee16283.jpg
asset:
id: 400974f1-10d8-4db9-a711-a840e315fdef
resourceUri: /authoring/v1/resources/fd95f9a53edd5c2ae4ebdf2ba4648d82
fileName: cap.jpg
fileSize: 113730
mediaType: image/jpeg
filekey:
elementType: file
asset:
id: 913099e2-3e53-497c-b264-77ed974b1694
resourceUri: /authoring/v1/resources/a9a19a26209fed0b96612d6263618d9b
fileSize: 145592
fileName: news.pdf
mediaType: application/pdf
numberkey:
elementType: number
value: 42
imagewithprofilekey:
elementType: image
renditions:
default:
renditionId: 39a94d18-9063-4785-80f8-cc5520255afe
source: /authoring/v1/resources/1decdf83-126a-4fc1-b9fc-d3d42297d576.jpg
mobile:
renditionId: 583d4fa3-7b3f-4c31-8aca-f1a32e3f5d6b
source: /authoring/v1/resources/1decdf83-126a-4fc1-b9fc-d3d42297d576.jpg?resize=0.16286644951140064xw:0.16286644951140064xh&crop=200:200;56,0
asset:
id: b4703646-2ae9-4ef3-8d2d-9f8a2d5f2545
resourceUri: /authoring/v1/resources/fd95f9a53edd5c2ae4ebdf2ba464a0f9
fileName: tree-738816_1920.jpg
fileSize: 273419
mediaType: image/jpeg
tags:
type: array
description: The tags describing the content item.
items:
type: string
uniqueItems: true
example:
- news
- sample
links:
type: object
properties:
self:
type: object
description: The default link back to this document
properties:
href:
type: string
example:
href: /authoring/v1/content/925d1454-167b-431b-a54c-6cbf0354398d
linkedDoc:
type: object
description: This link will appear if this item is a draft of an existing item. The link points to the primary item
properties:
href:
type: string
example:
href: /authoring/v1/content/fd95f9a53edd5c2ae4ebdf2ba464a0f9
draft:
type: object
description: This link will appear on an item if there exists a draft of this item. The link points to the draft.
properties:
href:
type: string
example:
href: /authoring/v1/content/fd95f9a53edd5c2ae4ebdf2ba464a0f9
create-draft:
type: object
description: This link will appear for items in ready and retired state that don't already have an existing draft. It will create a draft of this item.
properties:
href:
type: string
example:
href: /authoring/v1/content/925d1454-167b-431b-a54c-6cbf0354398d/create-draft
ready:
type: object
description: This link will appear for items that can be transitioned to the ready state.
properties:
href:
type: string
example:
href: /authoring/v1/content/925d1454-167b-431b-a54c-6cbf0354398d/ready
retire:
type: object
description: This link will appear for items that can be transitioned to the retired state.
properties:
href:
type: string
example:
href: /authoring/v1/content/925d1454-167b-431b-a54c-6cbf0354398d/retire
type:
type: object
description: This is the link to the content's type.
properties:
href:
type: string
example:
href: /authoring/v1/types/b0798e67-3da2-48b4-b044-016495fa3ead
thumbnail:
type: object
description: 'The reference to the resource that should act as the thumbnail of this content item.
The thumbnail can be referred to by either id or path.
This field is read only, and is determined by the contentThumbnail field on the content type. The type can specify an image element on this content item, or a specific image resource.
'
properties:
id:
type: string
description: The ID of the asset.
example: 6c622bbb-5f5b-45d4-89e1-fce1c054138f
path:
type: string
description: The path of the resource.
example: /sales/images/hub.png
url:
type: string
description: The url of the resource.
example: /authoring/v1/resources/47d535ff288b3bd8383009abf82a9ea8
isSystem:
type: boolean
description: Indicates whether this item is a 'system item' or not. 'System item' means that this is an item managed internally by Acoustic.
default: false
libraryId:
type: string
description: If this property is set it points to library id that the item is assigned to.
additionalProperties: false
'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 list the content items in the database as the service is currently unavailable. Try again later.
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
default:
description: Unexpected error.
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
x-ibm-dx-security-user-roles:
- admin
- manager
- editor
- viewer
post:
summary: Create content items.
description: "Use the /content endpoint to create content. A content type must be specified through the typeId property. You cannot create content without a content type.\n\n### Example: ###\nCreates a readied content that contains the name and birthday of a person.\n#\n~~~\n{\n \"name\": \"Person\",\n \"typeId\": \"b0798e67-3da2-48b4-b044-016495fa3ead\",\n \"status\": \"ready\",\n \"elements\": {\n \"name\": {\n \"elementType\": \"text\",\n \"value\": \"Thomas Watson\"\n },\n \"birthday\": {\n \"elementType\": \"datetime\",\n \"value\": \"1874-02-17T00:00:00Z\"\n }\n }\n}\n~~~\n<br />User roles: admin, manager, editor"
parameters:
- name: x-ibm-dx-publish-priority
in: header
description: Specify `now` to bypass the publishing schedule. Specify `next` to use publishing schedule.
schema:
type: string
format: string
enum:
- now
- next
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: The name of the content item.
example: Sample Content
typeId:
type: string
description: The ID of the content type this content item is based on.
example: b0798e67-3da2-48b4-b044-016495fa3ead
elements:
type: object
description: 'Elements are defined in the content type. A content type for a content is referenced through the typeId attribute. The elements in the content are based on the content type that is referenced. A content can have multiple elements such as text, number, video, images. For example, to include a text element include \"someTextElement\":{\"elementType\": \"text\", \"value\": \"some text goes here\" }. For a complete list of content elements, see https://developer.goacoustic.com/acoustic-content/reference#authoring-content
'
isSystem:
type: boolean
description: Indicates whether this item is a 'system item' or not. 'System item' means that this is an item managed internally by Acoustic.
default: false
libraryId:
type: string
description: If this property is set it points to library id that the item is assigned to.
required:
- name
- typeId
description: Provide the content item fields such as name, typeId, status and tags. The name and typeId fields are required.
required: true
tags:
- Authoring content
responses:
'201':
description: Successfully created a content item with the specified content type.
headers:
x-ibm-dx-validation-warnings:
description: The number of validation warnings that occurred. Use the /content/{id}/validate endpoint for a full list of any warnings.
schema:
type: integer
content:
application/json:
schema:
title: Content Schema
type: object
properties:
id:
type: string
description: The ID of the content item.
example: 925d1454-167b-431b-a54c-6cbf0354398d
rev:
type: string
description: The current revision of the document.
example: 25-2ba981d0661c3129c31cc4993e569e3f
name:
type: string
description: The name of the content item.
example: Sample Content
description:
type: string
description: The description of the content item.
example: An example description of the sample content
typeId:
type: string
description: The ID of the content type this item belongs to.
example: b0798e67-3da2-48b4-b044-016495fa3ead
type:
type: string
description: The name of the content type this item belongs to. Only included when using include=metadata
example: Article
kind:
type: string
description: The kind of the content. Recognized values are "site", "page", "landing-page", "email"
example: email
lastModified:
type: string
format: date-time
description: The last modified date of this content item in ISO 8601 with the format YYYY-MM-DDTHH:mm:ss.sssZ. This field is read only.
example: '2016-11-02T06:28:47Z'
lastModifierId:
type: string
description: The ID of the user that last modified the content.
example: 63b800fa-51a7-4602-8cbe-ab3b9cee28b9
lastModifier:
type: string
description: The display name of the user that last modified the content.
example: Thomas Watson
created:
type: string
format: date-time
description: The created date of this content item in ISO 8601 with the format YYYY-MM-DDTHH:mm:ss.sssZ. This field is read only.
example: '2016-11-02T06:28:47Z'
creatorId:
type: string
description: The ID of the creator of the content.
example: 8c622bbb-5f5b-45d4-89e1-fce1c054138f
creator:
type: string
description: The display name of the user that created the content.
example: Thomas Watson
classification:
description: The classification defines the document type. For content items, all documents are classified as "content".
enum:
- content
status:
description: the workflow status of the content.
enum:
- draft
- ready
- retired
# --- truncated at 32 KB (283 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/acoustic/refs/heads/main/openapi/acoustic-authoring-content-api-openapi.yml