openapi: 3.1.0
info:
title: Turbonomic REST API
description: >-
The IBM Turbonomic REST API provides programmatic access to the Turbonomic Application
Resource Management (ARM) platform. It enables automation of resource optimization
actions, querying of entities (VMs, containers, applications, storage), management of
markets and policies, retrieval of statistics and analytics, group management, template
administration, and topology exploration across hybrid cloud environments.
version: v3
contact:
name: IBM Turbonomic Support
url: https://www.ibm.com/mysupport/s/topic/0TO0z000000ZnCCGA0/turbonomic-application-resource-management
license:
name: IBM Terms of Service
url: https://www.ibm.com/terms
externalDocs:
description: Turbonomic REST API Reference
url: https://www.ibm.com/docs/en/tarm/8.19.3?topic=reference-turbonomic-rest-api-endpoints
servers:
- url: https://{turbonomic_host}/api/v3
description: Turbonomic Server
variables:
turbonomic_host:
description: The hostname or IP address of the Turbonomic server
default: turbonomic.example.com
tags:
- name: Authentication
description: Authenticate and manage sessions
- name: Entities
description: Query and manage entities (VMs, containers, applications, storage)
- name: Actions
description: Retrieve, accept, and reject optimization actions
- name: Markets
description: Access Turbonomic markets and projected states
- name: Groups
description: Create and manage logical groups of entities
- name: Policies
description: Manage automation and placement policies
- name: Statistics
description: Retrieve historical and projected resource statistics
- name: Templates
description: Manage resource and hardware templates
- name: Targets
description: Manage discovery targets and integrations
- name: Topology
description: Explore infrastructure topology and supply chains
- name: Reports
description: Access and generate operational reports
paths:
/login:
post:
operationId: loginUser
summary: Login to Turbonomic
description: Authenticate with the Turbonomic server and obtain a session token for subsequent API calls.
tags:
- Authentication
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- username
- password
properties:
username:
type: string
description: Turbonomic username
password:
type: string
description: Turbonomic password
responses:
'200':
description: Login successful
content:
application/json:
schema:
$ref: '#/components/schemas/AuthToken'
'401':
description: Invalid credentials
/logout:
post:
operationId: logoutUser
summary: Logout from Turbonomic
description: Invalidate the current session token.
tags:
- Authentication
security:
- bearerAuth: []
responses:
'200':
description: Logout successful
/entities:
get:
operationId: getEntities
summary: Get All Entities
description: >-
Retrieve all entities in the Turbonomic environment. Entities include
virtual machines, containers, applications, storage volumes, hosts, and
other infrastructure components.
tags:
- Entities
security:
- bearerAuth: []
parameters:
- name: entity_type
in: query
description: Filter by entity type (e.g., VirtualMachine, Container, Application)
schema:
type: string
- name: limit
in: query
description: Maximum number of entities to return
schema:
type: integer
default: 50
- name: cursor
in: query
description: Pagination cursor for the next page of results
schema:
type: string
responses:
'200':
description: List of entities
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Entity'
/entities/{uuid}:
get:
operationId: getEntityByUuid
summary: Get Entity By UUID
description: Retrieve a specific entity by its unique identifier.
tags:
- Entities
security:
- bearerAuth: []
parameters:
- name: uuid
in: path
required: true
description: The unique identifier of the entity
schema:
type: string
responses:
'200':
description: Entity details
content:
application/json:
schema:
$ref: '#/components/schemas/Entity'
'404':
description: Entity not found
/entities/{uuid}/actions:
get:
operationId: getEntityActions
summary: Get Entity Actions
description: Retrieve pending optimization actions for a specific entity.
tags:
- Entities
- Actions
security:
- bearerAuth: []
parameters:
- name: uuid
in: path
required: true
description: The unique identifier of the entity
schema:
type: string
responses:
'200':
description: List of actions for the entity
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Action'
/entities/{uuid}/stats:
get:
operationId: getEntityStats
summary: Get Entity Statistics
description: Retrieve historical and projected resource utilization statistics for an entity.
tags:
- Entities
- Statistics
security:
- bearerAuth: []
parameters:
- name: uuid
in: path
required: true
description: The unique identifier of the entity
schema:
type: string
- name: start_date
in: query
description: Start date for statistics (ISO 8601 format)
schema:
type: string
format: date-time
- name: end_date
in: query
description: End date for statistics (ISO 8601 format)
schema:
type: string
format: date-time
responses:
'200':
description: Entity statistics
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/StatSnapshot'
/markets:
get:
operationId: getMarkets
summary: Get All Markets
description: >-
Retrieve all Turbonomic markets. Markets represent simulation scenarios
used to project the state of the environment and evaluate optimization actions.
tags:
- Markets
security:
- bearerAuth: []
responses:
'200':
description: List of markets
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Market'
/markets/{uuid}/actions:
get:
operationId: getMarketActions
summary: Get Market Actions
description: >-
Retrieve all pending optimization actions for a market. By default, queries
the realtime market (Market) for all pending actions.
tags:
- Markets
- Actions
security:
- bearerAuth: []
parameters:
- name: uuid
in: path
required: true
description: Market UUID (use 'Market' for the realtime market)
schema:
type: string
- name: ascending
in: query
description: Sort order for results
schema:
type: boolean
default: false
responses:
'200':
description: List of actions in the market
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Action'
/markets/{uuid}/actions/stats:
post:
operationId: getMarketActionStats
summary: Get Market Action Statistics
description: Retrieve aggregate statistics for actions in a market filtered by criteria.
tags:
- Markets
- Statistics
security:
- bearerAuth: []
parameters:
- name: uuid
in: path
required: true
description: Market UUID
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ActionFilter'
responses:
'200':
description: Action statistics
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/StatSnapshot'
/actions/{uuid}:
get:
operationId: getActionByUuid
summary: Get Action By UUID
description: Retrieve details for a specific optimization action.
tags:
- Actions
security:
- bearerAuth: []
parameters:
- name: uuid
in: path
required: true
description: The unique identifier of the action
schema:
type: string
- name: accept
in: query
description: If true, execute (accept) this action
schema:
type: boolean
responses:
'200':
description: Action details
content:
application/json:
schema:
$ref: '#/components/schemas/Action'
'404':
description: Action not found
/groups:
get:
operationId: getGroups
summary: Get All Groups
description: Retrieve all entity groups defined in the Turbonomic environment.
tags:
- Groups
security:
- bearerAuth: []
parameters:
- name: group_type
in: query
description: Filter by group type
schema:
type: string
responses:
'200':
description: List of groups
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Group'
post:
operationId: createGroup
summary: Create Group
description: Create a new entity group for scoped policy application and reporting.
tags:
- Groups
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GroupInput'
responses:
'200':
description: Created group
content:
application/json:
schema:
$ref: '#/components/schemas/Group'
/groups/{uuid}:
get:
operationId: getGroupByUuid
summary: Get Group By UUID
description: Retrieve a specific entity group by its unique identifier.
tags:
- Groups
security:
- bearerAuth: []
parameters:
- name: uuid
in: path
required: true
description: The unique identifier of the group
schema:
type: string
responses:
'200':
description: Group details
content:
application/json:
schema:
$ref: '#/components/schemas/Group'
'404':
description: Group not found
put:
operationId: updateGroup
summary: Update Group
description: Update an existing entity group.
tags:
- Groups
security:
- bearerAuth: []
parameters:
- name: uuid
in: path
required: true
description: The unique identifier of the group
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GroupInput'
responses:
'200':
description: Updated group
content:
application/json:
schema:
$ref: '#/components/schemas/Group'
delete:
operationId: deleteGroup
summary: Delete Group
description: Delete an entity group.
tags:
- Groups
security:
- bearerAuth: []
parameters:
- name: uuid
in: path
required: true
description: The unique identifier of the group
schema:
type: string
responses:
'200':
description: Group deleted successfully
/policies:
get:
operationId: getPolicies
summary: Get All Policies
description: Retrieve all automation and placement policies defined in Turbonomic.
tags:
- Policies
security:
- bearerAuth: []
responses:
'200':
description: List of policies
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Policy'
post:
operationId: createPolicy
summary: Create Policy
description: Create a new automation or placement policy.
tags:
- Policies
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PolicyInput'
responses:
'200':
description: Created policy
content:
application/json:
schema:
$ref: '#/components/schemas/Policy'
/policies/{uuid}:
get:
operationId: getPolicyByUuid
summary: Get Policy By UUID
description: Retrieve a specific policy by its unique identifier.
tags:
- Policies
security:
- bearerAuth: []
parameters:
- name: uuid
in: path
required: true
description: The unique identifier of the policy
schema:
type: string
responses:
'200':
description: Policy details
content:
application/json:
schema:
$ref: '#/components/schemas/Policy'
'404':
description: Policy not found
put:
operationId: updatePolicy
summary: Update Policy
description: Update an existing policy.
tags:
- Policies
security:
- bearerAuth: []
parameters:
- name: uuid
in: path
required: true
description: The unique identifier of the policy
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PolicyInput'
responses:
'200':
description: Updated policy
content:
application/json:
schema:
$ref: '#/components/schemas/Policy'
delete:
operationId: deletePolicy
summary: Delete Policy
description: Delete a policy.
tags:
- Policies
security:
- bearerAuth: []
parameters:
- name: uuid
in: path
required: true
description: The unique identifier of the policy
schema:
type: string
responses:
'200':
description: Policy deleted successfully
/stats:
post:
operationId: getStats
summary: Get Statistics
description: Retrieve aggregated statistics for entities matching the specified criteria.
tags:
- Statistics
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/StatFilter'
responses:
'200':
description: Statistics results
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/StatSnapshot'
/targets:
get:
operationId: getTargets
summary: Get All Targets
description: >-
Retrieve all discovery targets configured in Turbonomic, including cloud
accounts, hypervisors, container platforms, and monitoring systems.
tags:
- Targets
security:
- bearerAuth: []
responses:
'200':
description: List of targets
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Target'
/targets/{uuid}:
get:
operationId: getTargetByUuid
summary: Get Target By UUID
description: Retrieve a specific discovery target by its unique identifier.
tags:
- Targets
security:
- bearerAuth: []
parameters:
- name: uuid
in: path
required: true
description: The unique identifier of the target
schema:
type: string
responses:
'200':
description: Target details
content:
application/json:
schema:
$ref: '#/components/schemas/Target'
'404':
description: Target not found
/templates:
get:
operationId: getTemplates
summary: Get All Templates
description: Retrieve all resource and hardware templates defined in Turbonomic.
tags:
- Templates
security:
- bearerAuth: []
responses:
'200':
description: List of templates
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Template'
post:
operationId: createTemplate
summary: Create Template
description: Create a new resource or hardware template.
tags:
- Templates
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TemplateInput'
responses:
'200':
description: Created template
content:
application/json:
schema:
$ref: '#/components/schemas/Template'
/templates/{uuid}:
get:
operationId: getTemplateByUuid
summary: Get Template By UUID
description: Retrieve a specific template by its unique identifier.
tags:
- Templates
security:
- bearerAuth: []
parameters:
- name: uuid
in: path
required: true
description: The unique identifier of the template
schema:
type: string
responses:
'200':
description: Template details
content:
application/json:
schema:
$ref: '#/components/schemas/Template'
'404':
description: Template not found
delete:
operationId: deleteTemplate
summary: Delete Template
description: Delete a template.
tags:
- Templates
security:
- bearerAuth: []
parameters:
- name: uuid
in: path
required: true
description: The unique identifier of the template
schema:
type: string
responses:
'200':
description: Template deleted successfully
/topology:
get:
operationId: getTopologyDefinitions
summary: Get Topology Definitions
description: Retrieve topology definitions describing infrastructure relationships and supply chains.
tags:
- Topology
security:
- bearerAuth: []
responses:
'200':
description: Topology definitions
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/TopologyDefinition'
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
Bearer token obtained by calling POST /api/v3/login with username and password.
Include in the Authorization header as 'Bearer {token}'.
schemas:
AuthToken:
type: object
description: Authentication token returned upon successful login
properties:
token:
type: string
description: Bearer token for subsequent API calls
username:
type: string
description: Authenticated username
uuid:
type: string
description: User UUID
roles:
type: array
items:
type: string
description: User roles
Entity:
type: object
description: A managed entity in the Turbonomic environment
properties:
uuid:
type: string
description: Unique identifier of the entity
displayName:
type: string
description: Human-readable name of the entity
className:
type: string
description: Entity type (e.g., VirtualMachine, Container, Application, PhysicalMachine)
environmentType:
type: string
description: Environment type (CLOUD, ON_PREM, HYBRID)
enum:
- CLOUD
- ON_PREM
- HYBRID
state:
type: string
description: Current operational state of the entity
severityBreakdown:
type: object
description: Summary of action severities for this entity
tags:
type: object
description: Key-value tags associated with the entity
additionalProperties:
type: array
items:
type: string
Action:
type: object
description: An optimization action recommended by Turbonomic
properties:
uuid:
type: string
description: Unique identifier of the action
actionType:
type: string
description: Type of action (e.g., RESIZE, MOVE, PROVISION, SUSPEND, DELETE)
actionMode:
type: string
description: Execution mode (MANUAL, AUTOMATIC, RECOMMEND, DISABLED)
details:
type: string
description: Human-readable description of the action
importance:
type: number
description: Importance score for prioritizing actions
severity:
type: string
description: Severity level (CRITICAL, MAJOR, MINOR)
state:
type: string
description: Current state of the action
createTime:
type: string
format: date-time
description: When the action was first generated
target:
$ref: '#/components/schemas/EntityRef'
newEntity:
$ref: '#/components/schemas/EntityRef'
currentEntity:
$ref: '#/components/schemas/EntityRef'
risk:
type: object
description: Risk assessment for this action
EntityRef:
type: object
description: A reference to an entity
properties:
uuid:
type: string
description: Entity UUID
displayName:
type: string
description: Entity display name
className:
type: string
description: Entity type
Market:
type: object
description: A Turbonomic market (real-time or plan scenario)
properties:
uuid:
type: string
description: Unique identifier of the market
displayName:
type: string
description: Human-readable name (e.g., 'Market' for real-time)
state:
type: string
description: Current state of the market
type:
type: string
description: Market type (REALTIME, PLAN)
Group:
type: object
description: A logical group of entities in Turbonomic
properties:
uuid:
type: string
description: Unique identifier of the group
displayName:
type: string
description: Human-readable name of the group
groupType:
type: string
description: Type of entities in this group
isStatic:
type: boolean
description: If true, the group has a fixed membership list
memberCount:
type: integer
description: Number of entities in the group
GroupInput:
type: object
description: Input for creating or updating a group
required:
- displayName
- groupType
properties:
displayName:
type: string
description: Human-readable name of the group
groupType:
type: string
description: Entity type for this group
isStatic:
type: boolean
description: If true, the group has a fixed membership list
memberUuids:
type: array
items:
type: string
description: For static groups, the list of member entity UUIDs
criteriaList:
type: array
items:
type: object
description: For dynamic groups, the filter criteria
Policy:
type: object
description: An automation or placement policy in Turbonomic
properties:
uuid:
type: string
description: Unique identifier of the policy
displayName:
type: string
description: Human-readable name of the policy
policyType:
type: string
description: Type of policy
enabled:
type: boolean
description: Whether the policy is active
PolicyInput:
type: object
description: Input for creating or updating a policy
required:
- displayName
properties:
displayName:
type: string
description: Human-readable name of the policy
policyType:
type: string
description: Type of policy
enabled:
type: boolean
description: Whether the policy should be active
StatSnapshot:
type: object
description: A statistical snapshot for a resource metric
properties:
date:
type: string
format: date-time
description: Timestamp of the statistic
statistics:
type: array
items:
type: object
properties:
name:
type: string
description: Name of the statistic (e.g., CPU, Mem, StorageAmount)
value:
type: number
description: Metric value
units:
type: string
description: Units for the value
StatFilter:
type: object
description: Filter criteria for retrieving statistics
properties:
statistics:
type: array
items:
type: object
properties:
name:
type: string
description: Statistic name to retrieve
period:
type: object
properties:
startDate:
type: string
format: date-time
endDate:
type: string
format: date-time
ActionFilter:
type: object
description: Filter criteria for retrieving action statistics
properties:
actionModeList:
type: array
items:
type: string
description: Filter by action modes
actionTypeList:
type: array
items:
type: string
description: Filter by action types
Target:
type: object
description: A discovery target connected to Turbonomic
properties:
uuid:
type: string
description: Unique identifier of the target
displayName:
type: string
description: Human-readable name of the target
type:
type: string
description: Target type (e.g., AWS, Azure, vCenter, Kubernetes)
status:
type: string
description: Validation status of the target
lastValidated:
type: string
format: date-time
description: When the target was last successfully validated
Template:
type: object
description: A resource or hardware template in Turbonomic
properties:
uuid:
type: string
description: Unique identifier of the template
displayName:
type: string
description: Human-readable name of the template
className:
type: string
description: Entity type this template applies to
price:
type: number
description: Cost associated with this template
TemplateInput:
type: object
description: Input for creating or updating a template
required:
- displayName
- className
properties:
displayName:
type: string
description: Human-readable name of the template
className:
type: string
description: Entity type this template applies to
TopologyDefinition:
type: object
description: A topology definition describing infrastructure relationships
properties:
uuid:
type: string
description: Unique identifier of the topology definition
displayName:
type: string
description: Human-readable name
description:
type: string
description: Description of this topology definition