Solution management API

The Solution management API enables external applications to work with solutions in UsageCloud. Use this API to create solutions, keep their names, colors, and annotations up to date, and read them back for dashboards, automation, or integration purposes, without a UsageCloud session.

A solution is the container that groups related streams. Every solution that you manage through this API belongs to the account of the application access whose credentials you use.

With the Solution management API, you can:

Create solution

• Create a solution in your account. The name is required. You can also set a color and an annotation. The name can contain letters, digits, spaces, and the characters - _ . ( ), and is at most 30 characters long. The annotation is a free-text note about the solution and is at most 5000 characters long. The color is one of 20 named palette colors: plum, purple, magenta, pink, navy, cobalt, blue, cyan, maroon, red, orange, yellow, forest, emerald, teal, mint, charcoal, slate, gray, and silver. The response returns the new solution, including its ID, the color name, the matching hex code, the creating principal, and the timestamps.

List solutions

• Retrieve all solutions in your account, with their names, colors, annotations, and timestamps.

Get solution

• Retrieve one solution by its ID, including its name, color, annotation, and timestamps.

Update solution

• Change the name, the color, or the annotation of a solution. Send only the fields you want to change, and at least one of them. To remove an annotation, send the annotation as null. The response returns the updated solution.

Deleting a solution is not available through the API. To delete a solution, use the Solutions page in UsageCloud, see Solutions.

Get solution statistics

• Retrieve, for every solution in your account, its name and color, along with the number of streams it holds and how many of them are running, failed, or deployed. The running, failed, and deployed counts don't add up to the total number of streams, because a stream can be counted in more than one of them. If the status of a solution's streams can't be determined, no status counts are returned for that solution.

Access to the Solution management API is secured. An admin user must first create an Application access with the three Solution management scopes: solution-management:read:solutions to list and get solutions, solution-management:create:solutions to create solutions, and solution-management:update:solutions to update them. A request without a valid access token is refused with status 401, and a request whose token lacks the scope for the operation is refused with status 403. The statistics endpoint uses the same solution-management:read:solutions scope as list and get; no additional scope is required.

Each endpoint allows up to two requests per second for each client, with a burst capacity of four requests. When you exceed the limit, the API responds with status 429. For more information, see Rate limits.

For more information on setting up APIs and links to the API documentation, see API access guide.