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