Overview
The Acoustic Content REST APIs allow you to work with the content in the database. You can
retrieve, update, and manage content. The APIs provide you with the flexibility of leveraging
existing content into various channels.
Access the Acoustic Content APIs from the API Explorer. Each API service operation has a set of user roles that are allowed for the operation. You can call only the service operations that are allowed for the specific role a user has. The roles are
- Administrator – can access all functionality including tenant administration tasks such as adding/removing users.
- Manager – can create and manage content model, content, and assets.
- Editor – can create and manage content and assets.
- Viewer – can retrieve content and assets.
- Anonymous – cannot access any authoring functionality.
- Requests from the client application can be returned with an HTTP status code 429. In such
cases, the best approach would be to retry the request after some time. - If a client program issues a high number of requests to Acoustic Content API, limit the
number of outstanding requests. Limiting the number of outstanding requests reduces the risk that
requests are replied with HTTP status code 429. In case the client would issue too many requests per
second, the request delay algorithm of Acoustic Content would limit the throughput.
Throughput limits for tenants
Acoustic Content is used simultaneously by multiple customers through their tenants. To
process resources for all customers, Acoustic Content limits the load that is imposed by each
tenant. The throughput limit for trial and paying customers can be different. If the number of
requests that are received by Acoustic Content is below the tenants throughput limit, the
requests are processed without delay.
Acoustic Content limits the number of requests per second per tenant, if the number of
incoming requests is above the throughput limit. The processing of the requests that are above the
limit are delayed for a certain time until they can be processed. If the delay time for processing
the requests is excessive, any additional requests are returned with the HTTP status code “429 Too
Many Requests”.
When you write client applications by using Acoustic Content, you must be aware of the
following scenarios:
You can use a command line interface (CLI) based utility wchtools to work with content, assets, and content model artifacts for Acoustic Content. The wchtools is an open source utility that you can install from GitHub. You can use the tool to upload and download from your Acoustic Content tenant. You can also use this tool to install sample content artifacts to your tenant, to bulk upload assets, and to trigger a publishing job.
Find more information about installing wchtools
The API documentation provides you with all the necessary information to get started.Before you start working with our APIs, take a look at a few use cases that demonstrate common business scenarios. These use cases will help you get a better context of the APIs may be relevant to your business needs.
Use cases
Import content to your product site or application
Accessing your content is quick and easy. Use our APIs to import the content into your products
that you use to deliver content to your customers, or directly into sites and application that you
may already have set up. For example, say that your business uses a marketing tool to help deliver
your promotional fliers and advertisements, you can access the content in Acoustic Content
with our APIs from the marketing tool and import the required images and content to the flier that
you plan to deliver.
Target content specific for your immediate business need
Accessing specific content that meets your business needs anytime and from anywhere is quick and
effortless. Say for example, your business manages publications and you have a news article that you
already have ready to be published. You realize that changes are happening and the image you
included is no longer relevant. With our APIs, you can access the exact image that you feel fit and
replace the one in your content without changing the text or any other elements in the article with
less effort. Choosing an exact image is made easy with the Watson tagging. Reference a tag that you
think matches the image that you want in your API and only the images that match the tag are
returned. For example, if you include the tag “White house” in your API call, only the images with
the tag “White house” are returned, thus narrowing your search scope.
The API documentation is also available at https://github.com/ibm-wch/wch-openapi-documentation in OpenAPI YAML format. You can process this file with your own tools or use an OpenAPI viewer of your choice to display the documentation.