Introduction
Welcome to the Morpheus API Documentation.
Morpheus is a powerful cloud management tool that provides provisioning, monitoring, logging, backups, and application deployment strategies.
This document describes the Morpheus API protocol and the available endpoints. Sections are organized in the same manner as they appear in the Morpheus UI.
Sections
To initialize a freshly installed Morpheus appliance, see Setup.
Version
You can determine your current version using Ping.
curl "$serverUrl/api/ping"
The above command returns JSON structured like this:
{
"success": true,
"buildVersion": "5.3.0.184",
"applianceUrl": "$serverUrl",
"setupNeeded": false
}
API
The Morpheus API is an HTTP interface for interacting with the Morpheus appliance. It provides a RESTful interface where GET reads, POST creates, PUT updates and DELETE destroys resources.
curl "$serverUrl/api/users/1" \
-H "Authorization: BEARER $accessToken"
The above command returns JSON structured like this:
{
"user": {
"id": 1,
"accountId": 1,
"username": "admin",
"displayName": "Morpheus Admin",
"email": "admin@morpheusdata.com",
"firstName": "Morpheus",
"lastName": "Admin",
"enabled": true,
"receiveNotifications": true,
"isUsing2FA": true,
"accountExpired": false,
"accountLocked": false,
"passwordExpired": false,
"loginCount": 42,
"loginAttempts": 0,
"lastLoginDate": "2021-04-17T00:12:01Z",
"roles": [
{
"id": 1,
"authority": "System Admin",
"description": "Super User"
}
],
"account": {
"id": 1,
"name": "morpheusdata.com"
},
"linuxUsername": "morphadmin",
"linuxPassword": null,
"linuxKeyPairId": 5,
"windowsUsername": "morphadmin",
"windowsPassword": "************",
"defaultPersona": {
"id": 1,
"code": "standard",
"name": "Standard"
},
"dateCreated": "2016-08-27T19:28:09Z",
"lastUpdated": "2021-04-17T00:12:01Z"
}
}
This is an example of a Morpheus API request that retrieves details about a User.
HTTP Request
GET $serverUrl/api/users/:id
HTTP Request describes the method and path of the endpoint. Most endpoints have a path formatted as /api/:resources/:id.
URL Parameters
| Parameter | Description |
|---|---|
| id | ID of the User. |
URL Parameters are variables which are included inside the path of the request.
HTTP Headers
| Header | Description |
|---|---|
| Authorization | Use the format BEARER ${access_token}. Example: Authorization: BEARER e1d62c34-f7f5-4713-a874-31491e7707de. Most endpoints require this header. Some exceptions include Authentication and Setup. |
| Content-Type | Use application/json for POST and PUT requests. This is needed to ensure your JSON payload is parsed. Exceptions to this rule include file uploads where application/x-www-form-urlencoded and application/octet-stream should be used instead. |
HTTP Headers are used to authorize the acting user via a valid access token, and to describe the type of content being sent, which is typically JSON.
Query Parameters
| Parameter | Description |
|---|---|
| phrase | If specified will return a partial match on name. |
Query Parameters are variables included in the query string portion of the request url, after the ? and they are delimited by &. Be sure to html encode your parameters and values!
JSON Parameters
| Parameter | Description |
|---|---|
| name | A unique string. |
JSON Parameters define the variables to be included in the body of the request. These are typically under the the context of an object, such as "contact".
HTTP Response
The HTTP status 200 OK will be returned when a request is successful and an HTTP Error status will be returned when a request fails.
Most endpoints respond with Content-Type: application/json and a body that contains JSON data.
This is an example of an API response that retrieves a Contact record by ID.
Example
curl "$serverUrl/api/monitoring/contacts/1" \
-H "Authorization: BEARER $accessToken"
The above command returns HTTP 200 and JSON structured like this:
{
"contact": {
"id": 1,
"name": "Morpheus Admin",
"emailAddress": "admin@morpheusdata.com",
"smsAddresss": null
}
}
This is an example of a successful response that contains the specified record.
Error Example
curl "$serverUrl/api/monitoring/contacts/999999" \
-H "Authorization: BEARER $accessToken"
The above command returns HTTP 404 and JSON structured like this:
{
"success": false,
"msg": "Contact not found for this account"
}
This is an example of a 404 error response returned when the specified record was not found.
Errors
When the Morpheus API encounters an error, the response will have an HTTP status of 400 of greater, instead of 200 OK. The error response body contains JSON with information to help troubleshoot the error.
400 Bad Request
curl -XPOST "$serverUrl/api/contacts" \
-H "Authorization: BEARER $accessToken" \
-d '{"contact":{"name":"example"}}'
The above command returns HTTP 400 and JSON structured like this:
{
"success": false,
"msg": "Unable to save contact",
"errors": {
"email": "Please enter a valid email address"
}
}
This error is returned if your request is invalid. Usually this is because a parameter is missing or the value is invalid. Try modifying your payload and retrying the request.
401 Unauthorized
curl "$serverUrl/api/instances"
The above command returns HTTP 401 and JSON structured like this:
{
"error": "unauthorized",
"error_description": "Full authentication is required to access this resource"
}
The unauthorized error will be encountered unless you pass the authorization header.
curl "$serverUrl/api/instances" \
-H "Authorization: BEARER BOGUS_TOKEN"
The above command returns HTTP 401 and JSON structured like this:
{
"error": "invalid_token",
"error_description": "Invalid access token: BOGUS_TOKEN"
}
The 401 error code is returned if your access token is invalid or expired.
403 Forbidden
curl "$serverUrl/api/setup" \
-H "Authorization: BEARER $accessToken"
The above command returns HTTP 403 and JSON structured like this:
{
"success": false,
"msg": "You do not have permissions to access this api endpoint"
}
This error is seen if you try to access an endpoint without the required permissions.
For this error example, use the token of user that does not have any admin permissions.
404 Not Found
curl "$serverUrl/api/foobar" \
-H "Authorization: BEARER $accessToken"
The above command returns HTTP 404 and JSON structured like this:
{
"success": false,
"msg": "Unable to find api endpoint GET /api/foobar"
}
This error indicates the specified endpoint path does not exist. Check the URL of your request and try again.
curl "$serverUrl/api/apps/99999" \
-H "Authorization: BEARER $accessToken"
The above command returns HTTP 404 and JSON structured like this:
{
"success": false,
"msg": "App not found"
}
The 404 error code is returned if a resource could be not be found by the specified ID.
500 Internal Server Error
curl "$serverUrl/api/test/500" \
-H "Authorization: BEARER $accessToken"
The above command returns HTTP 500 and JSON structured like this:
{
"success": false,
"msg": "Looks like the server threw a gasket"
}
This error indicates something went wrong with the request and an unexpected error has occured.
This example does not actually work and will return 404 instead. Hopefully you do not encounter a 500 error.
List of Error Codes
The Morpheus API uses the following error codes:
| Error Code | Description |
|---|---|
| 400 | Bad Request -- Your request failed. Check your request parameters and try again. |
| 401 | Unauthorized -- Your API key is invalid. Check your Authorization header. |
| 403 | Forbidden -- Your API key does not have the required role or permissions. |
| 404 | Not Found -- The specified resource could not be found. |
| 405 | Method Not Allowed -- You tried to access a resource with an invalid method. |
| 406 | Not Acceptable -- You requested a format that isn't json. |
| 410 | Gone -- The entity requested has been removed from our servers. |
| 418 | I'm a teapot. |
| 429 | Too Many Requests -- You're asking too much of the server. Slow down! |
| 500 | Internal Server Error -- We had a problem with our server. Try again later. |
| 503 | Service Unavailable -- We're temporarially offline for maintanance. Please try again later. |
Authentication
The Morpheus API uses an OAUTH 2.0 based authentication model.
Authentication is done by passing an access token in the Authorization HTTP header.
Use Get Access Token to acquire a valid access token.
Most /api endpoints require authentication, and will respond with a HTTP 401 without a valid Authorization header.
Authorization Header
This header must be included in all requests that require authorization.
| Header | Description |
|---|---|
| Authorization | Identifies the Morpheus API access token in the format bearer access_token. Example: Authorization: bearer e1d62c34-f7f5-4713-a874-31491e7707de |
Get Access Token
curl -XPOST "$serverUrl/oauth/token?grant_type=password&scope=write&client_id=morph-api" \
--data-urlencode 'username=admin' --data-urlencode 'password=foobar'
The above command returns JSON structured like this:
{
"access_token": "e1d62c34-f7f5-4713-a874-31491e7707de",
"refresh_token": "718cc628-b89f-43f5-bef7-f39887b47e68",
"token_type": "bearer",
"expires_in": 30463819,
"scope": "write"
}
This endpoint provides authentication via username and password of a Morpheus User. The response includes a valid access token. If your current token is expired, a new one will be created and returned.
HTTP Request
POST $serverUrl/oauth/token
HTTP Headers
| Header | Description |
|---|---|
| Content-Type | application/x-www-form-urlencoded must be passed, this endpoint does not accept application/json |
Query Parameters
| Parameter | Default | Description |
|---|---|---|
| client_id | Client ID, use morph-api. Users may only have one access token per Client ID. The CLI uses morph-cli. |
|
| grant_type | OAuth Grant Type, use password. |
|
| scope | OAuth token scope, use write. |
Request Parameters
| Parameter | Default | Description |
|---|---|---|
| username | User username. Subtenant users will need to pass their subdomain prefix like domain\username. The default subdomain is the tenant account ID. Example: 2\neo |
|
| password | User password |
Response
| Name | Description |
|---|---|
| access_token | The access token for this user (scoped to client_id). |
| refresh_token | The refresh token for this user (scoped to client_id). |
| expires_in | The remaining seconds before the token expires. By default, access tokens are valid for 1 year or until it is refreshed. This time may vary depending on the client_id that is used. |
| token_type | The token type, this will be bearer. |
| scope | The scope, this will be write. |
Refresh Access Token
curl -XPOST "$serverUrl/oauth/token?grant_type=refresh_token&client_id=morph-api&scope=write" \
-d 'refresh_token=718cc628-b89f-43f5-bef7-f39887b47e68'
The above command returns JSON structured like this:
{
"access_token": "e1d62c34-f7f5-4713-a874-31491e7707de",
"refresh_token": "718cc628-b89f-43f5-bef7-f39887b47e68",
"token_type": "bearer",
"expires_in": 30463819,
"scope": "write"
}
This endpoint allows refreshing your current access token to get a new token. This is done by passing your current refresh_token.
This provides a way to renew your client's session with the API, and extend the expiration date.
Your refresh_token is returned by Get Access Token.
HTTP Request
POST $serverUrl/oauth/token
HTTP Headers
| Header | Default | Description |
|---|---|---|
| Content-Type | Use application/x-www-form-urlencoded. |
Query Parameters
| Parameter | Default | Description |
|---|---|---|
| client_id | Client ID, use morph-api. Users only have one access token per Client ID. |
|
| grant_type | OAuth Grant Type, use refresh_token. |
|
| scope | OAuth token scope, use write. |
Request Body
| Parameter | Default | Description |
|---|---|---|
| refresh_token | Refresh Token, the current refresh token, scoped to Client ID. |
Response
| Name | Description |
|---|---|
| access_token | The access token for this user, scoped to Client ID. |
| refresh_token | The refresh token for this user, scoped to Client ID. |
| expires_in | The remaining seconds before the token expires. By default, access tokens are valid for 1 year or until it is refreshed. |
| token_type | The token type, this will be bearer. |
| scope | The scope, this will be write. |
Whoami
curl "$serverUrl/api/whoami" \
-H "Authorization: BEARER $accessToken"
The above command returns JSON structured like this:
{
"user": {
"id": 1,
"accountId": 1,
"username": "test",
"displayName": "Test U",
"email": "testuser@morpheusdata.com",
"firstName": "Test",
"lastName": "User",
"dateCreated": "2016-08-27T19:28:09+0000",
"lastUpdated": "2020-01-07T05:19:20+0000",
"enabled": true,
"accountExpired": false,
"accountLocked": false,
"passwordExpired": false,
"loginCount": 1575,
"loginAttempts": 0,
"lastLoginDate": "2020-01-07T05:19:20+0000",
"roles": [
{
"id": 5,
"authority": "Standard User",
"description": "A basic user role"
}
],
"account": {
"id": 1,
"name": "root"
},
"windowsUsername": "morphtest",
"linuxUsername": "morphtest"
},
"isMasterAccount": true,
"permissions": [
{
"name": "Provisioning: Blueprints",
"code": "app-templates",
"access": "full"
},
{
"name": "Provisioning: Apps",
"code": "apps",
"access": "full"
},
{
"name": "Logs",
"code": "logs",
"access": "full"
},
{
"name": "Monitoring",
"code": "monitoring",
"access": "full"
},
{
"name": "Operations: Wiki",
"code": "operations-wiki",
"access": "full"
},
{
"name": "Provisioning: Instances",
"code": "provisioning",
"access": "full"
},
{
"name": "Operations: Reports",
"code": "reports",
"access": "full"
},
{
"name": "Provisioning: Tasks - Script Engines",
"code": "task-scripts",
"access": "full"
},
{
"name": "Provisioning: Tasks",
"code": "tasks",
"access": "full"
},
{
"name": "Remote Console: Auto Login",
"code": "terminal-access",
"access": "yes"
},
{
"name": "Remote Console",
"code": "terminal",
"access": "full"
},
{
"name": "Provisioning: Blueprints - Terraform",
"code": "terraform-template",
"access": "full"
},
{
"name": "Provisioning: Virtual Images",
"code": "virtual-images",
"access": "full"
}
],
"appliance": {
"buildVersion": "4.1.2"
}
}
Provides API to retrieve information about yourself, including your roles and permissions.
The appliance build version is also returned.
HTTP Request
GET $serverUrl/api/whoami
Forgot Password
curl -XPOST "$serverUrl/api/forgot/send-email" \
-H "Content-Type: application/json" \
-d '{
"username": "example"
}'
The above command returns JSON structured like this:
{
"success": true,
"msg": "Reset password instructions have been sent to the user 'example', if they exist."
}
This endpoint will trigger the Reset your password email to be sent to the specified user.
The User is identified by username and, if they exist, will be notified via their configured email address. The email notification will indicate a Reset Password Request was made and it will include a token.
Once you obtain the token from the email, it may be used to reset the password of your user.
HTTP Request
POST $serverUrl/api/forgot/send-email
Request Parameters
| Parameter | Default | Description |
|---|---|---|
| username | Username of the User who would like to reset their password. Subtenant users will need to pass their subdomain prefix like domain\username. The default subdomain is the tenant account ID. Example: 2\neo |
Reset Password
curl -XPOST "$serverUrl/api/forgot/reset-password" \
-H "Content-Type: application/json" \
-d '{
"token": "3d0e0f652f884196b2349756b89f3dfd"
"password": "WywCx@L5rM5f3W^a"
}'
The above command returns JSON structured like this:
{
"success": true,
"msg": "Password has been updated and account unlocked"
}
This endpoint will reset the password for a user, updating it to the specified value. A secret token must be passed to identify the user who is being updated.
HTTP Request
POST $serverUrl/api/forgot/reset-password
Request Parameters
| Parameter | Default | Description |
|---|---|---|
| token | The secret Reset Password token that was included in the Forgot Password Email. | |
| password | User new password. This is the new password for your user |
Operations
The Operations API endpoints provide insight into the Morpheus appliance, activity, reports and approvals. Documentation can be viewed and modified via the Wiki API.
Dashboard
curl "$serverUrl/api/dashboard" \
-H "Authorization: BEARER $accessToken"
The above command returns JSON structured like this:
{
"success": true,
"monitoring": {
"avgHealth": 8.3333333333,
"avgResponseTime": 22.3333333333,
"warningApps": 0,
"warningChecks": 0,
"failApps": 0,
"totalApps": 2,
"failChecks": 1,
"successApps": 2,
"mutedApps": 0,
"successChecks": 5,
"totalChecks": 6,
"mutedChecks": 0,
"responseTimes": [
0,
2,
2,
125,
5,
0,
0
],
"allSuccess": false,
"openIncidents": 0
},
"provisioning": {
"instanceCount": 3,
"favoriteInstances": [
{
"id": 319,
"accountId": 1,
"instanceType": {
"id": 6,
"code": "apache",
"category": "web",
"name": "Apache"
},
"zones": [
{
"id": 40,
"accountId": 1,
"groups": [
1
],
"name": "qa-azure2",
"description": null,
"location": null,
"visibility": "private",
"zoneTypeId": 9
}
],
"layout": {
"id": 1292,
"code": "apache-azure-2.4-ubuntu-16.04-single",
"name": "Azure Apache",
"description": "This will provision a single process with no redundancy",
"sortOrder": 10
},
"plan": {
"name": "Basic_A0 (1 Core, 0.75GB Memory) (westus)",
"id": 187,
"code": "azure.plan.westus.Basic_A0"
},
"name": "test-azureapache1",
"displayName": "test-azureapache1",
"description": null,
"dateCreated": "2019-09-18T16:07:47Z",
"lastUpdated": "2019-10-25T09:12:29Z",
"status": "unknown",
"containerIds": [
317
],
"containers": [
{
"ip": "0.0.0.0",
"port": {
"id": 19,
"exportName": "HTTP",
"container": {
"id": 317
},
"loadBalancerInstance": null,
"primaryPort": false,
"loadBalanceProtocol": null,
"linkPort": true,
"internalPort": 80,
"export": true,
"portType": {
"id": 8
},
"displayName": "Http",
"protocol": "http",
"portIndex": 0,
"externalIp": null,
"externalPort": 80,
"internalIp": null,
"visible": true,
"loadBalance": true
}
}
],
"version": "2.4",
"environmentPrefix": null
}
]
},
"instanceStats": {
"usedMemory": 479804000,
"maxMemory": 1771446368,
"usedStorage": 6202490880,
"maxStorage": 55530786816,
"running": 2,
"total": 3,
"totalContainers": 4
},
"backups": {
"accountStats": {
"totalSizeByDay": [
0,
0,
0,
0,
0
],
"totalSizeByDay7Days": [
0,
0,
0,
0,
0,
0,
0
],
"formattedTotalSize": {
"value": "0",
"units": "KB"
},
"backupCount": 3,
"totalSize": 0,
"success": 0,
"failed": 0,
"totalCompleted": 0,
"avgSize": 0,
"failedRate": 0,
"successRate": 0,
"nextFireTotal": 1,
"backupDayCount": [
0,
0,
0,
0,
0,
0,
0
],
"backupDayCountTotal": 0
}
},
"activity": [
{
"success": false,
"name": "dev-appliance",
"message": "Check successfully been created.",
"ts": "2019-10-22T00:06:20Z",
"activityType": "Monitoring",
"accountId": 1,
"userId": 1,
"userName": "admin",
"objectId": 238,
"objectType": "MonitorCheck",
"_id": "0276e1fc-214d-4cb3-bcf4-9ebda0b26542",
"timestamp": "2019-10-22T00:06:20Z"
},
{
"success": true,
"name": "admin",
"message": "User 'admin' updated. Password changed.",
"ts": "2019-10-08T21:17:52Z",
"activityType": "Admin",
"accountId": 1,
"userId": 1,
"userName": "admin",
"objectId": 96,
"objectType": "User",
"_id": "26976fe0-a722-4d20-9849-9405a95d0db9",
"timestamp": "2019-10-08T21:17:52Z"
}
]
}
This endpoint can be used to view dashboard information about the remote Morpheus appliance. This is an overview and summary of data available to the user that can be used to render a dashboard.
HTTP Request
GET $serverUrl/api/dashboard
Reports
Provides API interfaces for viewing report results and executing new reports.
Get All Report Types
curl "$serverUrl/api/report-types" \
-H "Authorization: BEARER $accessToken"
The above command returns JSON structured like this:
{
"reportTypes": [
{
"id": 21,
"code": "appCost",
"name": "Application Cost",
"category": "cost",
"dateCreated": "2018-05-02T07:44:46+0000",
"optionTypes": [
{
"id": 1073,
"name": "endDate",
"code": "reportType.endDate",
"description": null,
"fieldName": "endDate",
"fieldLabel": "End Date",
"fieldContext": "report",
"fieldGroup": null,
"fieldClass": null,
"fieldAddOn": null,
"fieldComponent": null,
"placeHolder": null,
"helpBlock": "",
"defaultValue": null,
"optionSource": null,
"type": "text",
"advanced": false,
"required": true,
"editable": true,
"creatable": null,
"config": {
},
"displayOrder": 2,
"wrapperClass": null,
"enabled": true,
"noBlank": false,
"dependsOnCode": null,
"contextualDefault": false
}
]
},
{
"id": 26,
"code": "workloadSummary",
"name": "Workload Summary",
"category": "provisioningInventory",
"dateCreated": "2018-09-10T08:18:04+0000",
"optionTypes": [
]
}
],
"meta": {
"size": 18,
"total": 18,
"offset": 0,
"max": 25
}
}
This endpoint retrieves all available report types. A report type has optionTypes that define the parameters available when executing a report of that type. The sample response has been abbreviated.
HTTP Request
GET $serverUrl/api/report-types
Query Parameters
| Parameter | Default | Description |
|---|---|---|
| max | 25 | Max number of results to return |
| offset | 0 | Offset of records you want to load |
| sort | name | Sort order |
| direction | asc | Sort direction, use 'desc' to reverse sort |
| phrase | If specified will return a partial match on name | |
| name | If specified will return an exact match on name | |
| code | If specified will return an exact match on code | |
| category | If specified will return an exact match on category |
Get All Reports
curl "$serverUrl/api/reports" \
-H "Authorization: BEARER $accessToken"
The above command returns JSON structured like this:
{
"reportResults": [
{
"id": 2,
"type": {
"id": 21,
"code": "appCost",
"name": "Application Cost"
},
"reportTitle": "Application Cost Jun 04, 2019 19:28:02",
"filterTitle": "Jun 04, 2019",
"status": "ready",
"dateCreated": "2019-06-04T23:28:02+0000",
"lastUpdated": "2019-06-04T23:28:02+0000",
"startDate": null,
"endDate": null,
"config": {
"type": "appCost"
},
"createdBy": {
"id": 1,
"username": "root"
}
},
{
"id": 1,
"type": {
"id": 6,
"code": "groupInventory",
"name": "Group Inventory Summary"
},
"reportTitle": "Group Inventory Summary Jul 12, 2019 16:30:04",
"filterTitle": "Jul 12, 2019 | All Clouds | foo:bar",
"status": "ready",
"dateCreated": "2019-07-12T20:30:04+0000",
"lastUpdated": "2019-07-12T20:30:04+0000",
"startDate": null,
"endDate": null,
"config": {
"reportType": "groupInventory",
"cloudId": "",
"environment": "",
"tagName": "foo",
"tagValue": "bar"
},
"createdBy": {
"id": 1,
"username": "root"
}
}
],
"meta": {
"size": 2,
"total": 2,
"offset": 0,
"max": 25
}
}
This endpoint returns all reports. This is results of reports that have been executed in the past.
HTTP Request
GET $serverUrl/api/reports
Query Parameters
| Parameter | Default | Description |
|---|---|---|
| max | 25 | Max number of results to return |
| offset | 0 | Offset of records you want to load |
| sort | name | Sort order, default is dateCreated with direction desc |
| direction | asc | Sort direction, use 'desc' to reverse sort |
| phrase | If specified will return a partial match on name | |
| name | If specified will return an exact match on name | |
| reportType | If specified will return an exact match on report type code, accepts multiple values | |
| category | If specified will return an exact match on report type category, accepts multiple values |
Get a Specific Report
curl "$serverUrl/api/reports/2" \
-H "Authorization: BEARER $accessToken"
The above command returns JSON structured like this:
{
"reportResult": {
"id": 2,
"type": {
"id": 21,
"code": "appCost",
"name": "Application Cost"
},
"reportTitle": "Application Cost Jun 04, 2019 19:28:02",
"filterTitle": "Jun 04, 2019",
"status": "ready",
"dateCreated": "2019-06-04T23:28:02+0000",
"lastUpdated": "2019-06-04T23:28:02+0000",
"startDate": null,
"endDate": null,
"config": {
"type": "appCost"
},
"createdBy": {
"id": 1,
"username": "root"
},
"rows": [
{
"id": 536,
"section": "header",
"data": "{\"code\":\"totalCount\",\"name\":\"Apps\",\"value\":2",
"displayOrder": 0
},
{
"id": 535,
"section": "header",
"data": "{\"code\":\"totalCost\",\"name\":\"Total Cost\",\"value\":99.99,\"currency\":\"USD\"}",
"displayOrder": 0
},
{
"id": 534,
"section": "main",
"data": "{\"name\":\"testapp1\",\"cost\":0,\"price\":0,\"currency\":\"USD\"}",
"displayOrder": 0
},
{
"id": 533,
"section": "main",
"data": "{\"name\":\"testapp2\",\"cost\":99.99,\"price\":0,\"currency\":\"USD\"}",
"displayOrder": 1
}
]
}
}
This endpoint retrieves a specific report result. The response includes the result data as rows which can be used to render the report. Each report type will have sections for data and headers that vary by type, use Download a Specific Report to get the results organized by section.
HTTP Request
GET $serverUrl/api/reports/:id
URL Parameters
| Parameter | Description |
|---|---|
| id | ID of the report result |
Download a Specific Report
curl "$serverUrl/api/reports/download/3" \
-H "Authorization: BEARER $accessToken"
The above command returns
Content-Type: "application/octet-stream"andContent-disposition: attachment;filename=reportTitle.json. The body contains JSON structured like this:
{
"data": [
{
"name": "dev-amazon",
"cost": 7.199999999999999,
"price": 7.199999999999999,
"currency": "USD",
"deleted": false,
"hostCount": 0,
"instanceCount": 2,
"discoveredCount": 2
},
{
"name": "dev-azure",
"cost": 4775.508356680239,
"price": 4775.508356680239,
"currency": "USD",
"deleted": false,
"hostCount": 126,
"instanceCount": 0,
"discoveredCount": 1
},
],
"headers": [
{
"code": "totalCost",
"name": "Total Cost",
"value": 4782.7083566802385,
"displayOrder": 4,
"currency": "USD"
},
{
"code": "instanceCount",
"name": "Instances",
"value": 5,
"displayOrder": 2
},
{
"code": "count",
"name": "Clouds",
"value": 2,
"displayOrder": 0
},
{
"code": "discoveredCount",
"name": "Discovered VMs",
"value": 13,
"displayOrder": 3
},
{
"code": "hostCount",
"name": "Nodes",
"value": 127,
"displayOrder": 2
}
],
"footers": [
],
"reportType": "Cloud Cost",
"reportTypeId": 5,
"resultId": 146,
"reportDate": "2021-08-26T16:59:45Z",
"createdBy": "admin",
"createdById": 1
}
This endpoint downloads a specific report result as a file attachment. The default file format is json.
HTTP Request
GET $serverUrl/api/reports/download/:id(.:format)
URL Parameters
| Parameter | Description |
|---|---|
| id | ID of the report result |
| format | Format of the rendered report file, json or csv. The default is .json. |
Run a Report
curl -XPOST "$serverUrl/api/reports" \
-H "Authorization: BEARER $accessToken" \
-H "Content-Type: application/json" \
-d '{
"report": {
"type": "appCost",
"startDate": "2019-01-01",
"endDate": "2020-01-01"
}}'
The above command returns JSON structured like getting a single report:
This endpoint execute the specified report type and create a new report result.
HTTP Request
POST $serverUrl/api/reports
JSON Report Parameters
| Parameter | Default | Description |
|---|---|---|
| type | The Report Type code to be executed. |
The available parameters vary by report type. Refer to the defined optionTypes for each report.
JSON Common Report Parameters
| Parameter | Default | Description |
|---|---|---|
| startDate | The start date for the report | |
| endDate | The end date for the report | |
| groupId | The Group ID filter for the report | |
| cloudId | The Cloud ID filter for the report |
Delete a Report
curl -XDELETE "$serverUrl/api/reports/1" \
-H "Authorization: BEARER $accessToken"
The above command returns JSON Structured like this:
{
"success": true
}
This endpoint will delete a report result.
HTTP Request
DELETE $serverUrl/api/reports/:id
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the report result. |
Guidance
Provides API interfaces for managing guidance within Morpheus.
Get All Discoveries
curl "$serverUrl/api/guidance" \
-H "Authorization: BEARER $accessToken"
The above command returns JSON structured like this:
{
"discoveries": [
{
"id": 3405,
"dateCreated": "2019-03-05T23:05:02+0000",
"lastUpdated": "2020-03-21T00:05:05+0000",
"actionCategory": "reservation",
"actionMessage": "Reservation recommentations",
"actionTitle": "reserve.compute",
"actionType": "reserve",
"actionValue": "34.519463385782942",
"actionValueType": "reservation",
"actionPlanId": null,
"statusMessage": "Reservation recommendations for cloud QA Azure",
"accountId": 1,
"userId": null,
"siteId": 2,
"zone": {
"id": 4,
"name": "QA Azure",
"zoneType": {
"id": 9,
"name": "Azure (Public)"
}
},
"state": "processed",
"stateMessage": "shutdown resource",
"severity": "info",
"resolved": false,
"resolvedMessage": null,
"refType": "computeZone",
"refId": 4,
"refName": "QA Azure",
"type": {
"id": 6,
"name": "Reservation Recommendation",
"code": "reservations",
"title": "Add Reservations"
},
"savings": {
"amount": 34.51946338578294,
"currency": "USD"
},
"config": {
"success": true,
"detailList": [
{
"id": "billingAccount/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/providers/Microsoft.Consumption/reservationRecommendations/90bfe546-0ea4-8e62-4afb-975bbc9e83ac",
"apiName": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"apiType": "Microsoft.Consumption/reservationRecommendations",
"externalId": "Standard_D2",
"period": "Last30Days",
"name": "Standard_D2",
"type": "Standard_D2",
"category": "Standard_D2",
"size": "Standard_D2 (Cores: 2, Memory: 7 GB) (eastus)",
"region": "westus",
"term": "P1Y",
"meterId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"onDemandCount": 0,
"onDemandCost": 110.99038119400001,
"reservedCount": 0,
"reservedCost": 0,
"recommendedCount": 1,
"recommendedCost": 76.47091780821707,
"totalSavings": 34.51946338578294,
"totalSavingsPercent": 0.311013107752521
}
],
"services": {
"azureVms": {
"code": "azureVms",
"name": "Azure Virtual Machines",
"paymentOptions": {
"NO_UPFRONT": {
"code": "NO_UPFRONT",
"name": "No Upfront",
"termOptions": {
"{code=P1Y, name=1 Year, defaultOption=true}": {
"code": "P1Y",
"name": "1 Year",
"detailList": [
{
"id": "billingAccount/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/providers/Microsoft.Consumption/reservationRecommendations/90bfe546-0ea4-8e62-4afb-975bbc9e83ac",
"apiName": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"apiType": "Microsoft.Consumption/reservationRecommendations",
"externalId": "Standard_D2",
"period": "Last30Days",
"name": "Standard_D2",
"type": "Standard_D2",
"category": "Standard_D2",
"size": "Standard_D2 (Cores: 2, Memory: 7 GB) (eastus)",
"region": "westus",
"term": "P1Y",
"meterId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx5",
"onDemandCount": 0,
"onDemandCost": 110.99038119400001,
"reservedCount": 0,
"reservedCost": 0,
"recommendedCount": 1,
"recommendedCost": 76.47091780821707,
"totalSavings": 34.51946338578294,
"totalSavingsPercent": 0.311013107752521
}
],
"summary": {
"totalSavings": 34.51946338578294,
"currencyCode": "USD",
"totalSavingsPercent": 0.311013107752521,
"term": "",
"paymentOption": "",
"service": "compute",
"onDemandCount": 0,
"onDemandCost": 110.99038119400001,
"reservedCount": 0,
"reservedCost": 0,
"recommendedCount": 1,
"recommendedCost": 76.47091780821707
}
},
"{code=P3Y, name=3 Year}": {
"code": "P3Y",
"name": "3 Year",
"detailList": [
{
"id": "billingAccount/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/providers/Microsoft.Consumption/reservationRecommendations/90bfe546-0ea4-8e62-4afb-975bbc9e83ac",
"apiName": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"apiType": "Microsoft.Consumption/reservationRecommendations",
"externalId": "Standard_D2",
"period": "Last30Days",
"name": "Standard_D2",
"type": "Standard_D2",
"category": "Standard_D2",
"size": "Standard_D2 (Cores: 2, Memory: 7 GB) (eastus)",
"region": "westus",
"term": "P3Y",
"meterId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"onDemandCount": 0,
"onDemandCost": 110.99038119400001,
"reservedCount": 0,
"reservedCost": 0,
"recommendedCount": 1,
"recommendedCost": 49.160529680364135,
"totalSavings": 61.82985151363587,
"totalSavingsPercent": 0.557073963063191
}
],
"summary": {
"totalSavings": 61.82985151363587,
"currencyCode": "USD",
"totalSavingsPercent": 0.557073963063191,
"term": "",
"paymentOption": "",
"service": "compute",
"onDemandCount": 0,
"onDemandCost": 110.99038119400001,
"reservedCount": 0,
"reservedCost": 0,
"recommendedCount": 1,
"recommendedCost": 49.160529680364135
}
}
}
}
}
}
},
"summary": {
"totalSavings": 34.51946338578294,
"currencyCode": "USD",
"totalSavingsPercent": 0.311013107752521,
"term": "",
"paymentOption": "",
"service": "compute",
"onDemandCount": 0,
"onDemandCost": 110.99038119400001,
"reservedCount": 0,
"reservedCost": 0,
"recommendedCount": 1,
"recommendedCost": 76.47091780821707
}
}
}
],
"meta": {
"size": 1,
"total": 1,
"max": 50,
"offset": 0
}
}
This endpoint retrieves discoveries. By default, only includes discoveries that have not been ignored or executed.
HTTP Request
GET $serverUrl/api/guidance
Query Parameters
| Parameter | Default | Description |
|---|---|---|
| max | 25 | Max number of results to return |
| offset | 0 | Offset of records you want to load |
| sort | name | Sort order |
| direction | asc | Sort direction, use 'desc' to reverse sort |
| phrase | Reference name, status message and action, restricts query to only load discoveries which contain the phrase specified | |
| severity | Severity level filter, restricts query to only load discoveries of specified severity level: info, low, warning, critical | |
| type | Discovery type filter, restricts query to only load discoveries of specified discover type. See discovery types | |
| state | Filter by state, restricts query to only load discoveries by state: any, processed, ignored |
Get a Specific Discovery
curl "$serverUrl/api/guidance/2" \
-H "Authorization: BEARER $accessToken"
The above command returns JSON structured like this:
{
"discovery": {
"id": 2,
"dateCreated": "2020-03-18T17:36:09+0000",
"lastUpdated": "2020-03-21T18:49:27+0000",
"actionCategory": "power",
"actionMessage": "Shutdown 10.30.21.76",
"actionTitle": "shutdown",
"actionType": "shutdown",
"actionValue": "off",
"actionValueType": "power",
"actionPlanId": null,
"statusMessage": "Utilization for virtual machine 10.30.21.76 suggests it is not in use",
"accountId": 1,
"userId": null,
"siteId": null,
"zone": {
"id": 4,
"name": "Denver VMware Virtual Center Cloud",
"zoneType": {
"id": 14,
"name": "VMware vCenter"
}
},
"state": "processed",
"stateMessage": "shutdown resource",
"severity": "info",
"resolved": true,
"resolvedMessage": null,
"refType": "computeServer",
"refId": 6,
"refName": "10.30.21.76",
"type": {
"id": 1,
"name": "Shutdown",
"code": "shutdown",
"title": "Shutdown resource"
},
"savings": {
"amount": 40.0,
"currency": "USD"
},
"resource": {
"id": 6,
"externalId": "host-58630",
"internalId": null,
"externalUniqueId": null,
"accountId": 1,
"account": {
"name": "Stubby Toes Inc."
},
"name": "10.30.21.76",
"visibility": "private",
"description": null,
"zoneId": 4,
"siteId": 4,
"resourcePoolId": 9,
"folderId": null,
"sshHost": null,
"sshPort": 22,
"externalIp": null,
"internalIp": null,
"volumeId": null,
"platform": null,
"platformVersion": null,
"sshUsername": "xxxxx",
"sshPassword": null,
"osDevice": "/dev/sda",
"osType": "esxi",
"dataDevice": "/dev/sdb",
"lvmEnabled": true,
"apiKey": "xxxxx",
"softwareRaid": false,
"dateCreated": "2019-07-29T19:05:31+0000",
"lastUpdated": "2020-02-26T07:10:59+0000",
"stats": {
"ts": "2020-02-26T07:10:59Z",
"freeMemory": 94497890304,
"maxMemory": 137402474496,
"usedMemory": 42904584192,
"maxStorage": 3000483446784,
"usedStorage": 897040577986,
"cpuUsage": 10.99583333
},
"status": "provisioned",
"statusMessage": null,
"errorMessage": null,
"statusDate": "2019-07-29T19:05:31+0000",
"statusPercent": null,
"statusEta": null,
"powerState": "on",
"computeServerType": {
"id": 157,
"code": "vmwareHypervisor",
"name": "vSphere Hypervisor",
"managed": false,
"externalDelete": false
},
"agentInstalled": false,
"lastAgentUpdate": null,
"agentVersion": null,
"maxCores": 12,
"maxMemory": 137402474496,
"maxStorage": 3000483446784,
"maxCpu": null,
"serverOs": {
"id": 53,
"name": "esxi 6",
"description": null,
"vendor": "vmware",
"category": "esxi",
"osFamily": null,
"osVersion": "6",
"bitCount": 64,
"platform": "esxi"
},
"enabled": true,
"tagCompliant": null,
"zone": {
"id": 4,
"name": "VMware Virtual Center Cloud"
},
"plan": {
"id": null,
"code": null,
"name": null
},
"containers": [
]
},
"config": {
"exists": true,
"objectId": 6,
"networkBandwidthCount": 0,
"networkBandwidthMin": 0,
"networkBandwidthMax": 0,
"networkBandwidthAvg": 0,
"networkBandwidthSum": 0,
"netRxUsageCount": 5,
"netRxUsageMin": 0,
"netRxUsageMax": 185.0,
"netRxUsageAvg": 108.2,
"netRxUsageSum": 541.0,
"cpuSystemTimeCount": 0,
"cpuSystemTimeMin": 0,
"cpuSystemTimeMax": 0,
"cpuSystemTimeAvg": 0,
"cpuSystemTimeSum": 0,
"cpuTotalTimeCount": 0,
"cpuTotalTimeMin": 0,
"cpuTotalTimeMax": 0,
"cpuTotalTimeAvg": 0,
"cpuTotalTimeSum": 0,
"cpuUsageCount": 0,
"cpuUsageMin": 0,
"cpuUsageMax": 0,
"cpuUsageAvg": 0,
"cpuUsageSum": 0,
"netTxUsageCount": 5,
"netTxUsageMin": 0,
"netTxUsageMax": 244.0,
"netTxUsageAvg": 156.4,
"netTxUsageSum": 782.0,
"cpuUserTimeCount": 0,
"cpuUserTimeMin": 0,
"cpuUserTimeMax": 0,
"cpuUserTimeAvg": 0,
"cpuUserTimeSum": 0,
"cpuIdleTimeCount": 0,
"cpuIdleTimeMin": 0,
"cpuIdleTimeMax": 0,
"cpuIdleTimeAvg": 0,
"cpuIdleTimeSum": 0
}
}
}
This endpoint retrieves a specific discovery.
HTTP Request
GET $serverUrl/api/guidance/:id
URL Parameters
| Parameter | Description |
|---|---|
| id | ID of the discovery |
Get Guidance Stats
curl "$serverUrl/api/guidance/stats" \
-H "Authorization: BEARER $accessToken"
The above command returns JSON structured like this:
{
"stats": {
"total": 14,
"savings": {
"amount": -165.98050103021708,
"currency": "USD"
},
"severity": {
"low": 0,
"info": 14,
"warning": 0,
"critical": 0
},
"type": {
"size": 13,
"shutdown": 0,
"move": 0,
"schedule": 0
}
}
}
This endpoint retrieves a summary of actionable discoveries.
HTTP Request
GET $serverUrl/api/guidance/stats
Get Discovery Types
curl "$serverUrl/api/guidance/types" \
-H "Authorization: BEARER $accessToken"
The above command returns JSON structured like this:
{
"types": [
{
"id": 1,
"name": "Shutdown",
"code": "shutdown",
"category": "utilization",
"title": "Shutdown resource"
},
{
"id": 2,
"name": "Sizing",
"code": "size",
"category": "utilization",
"title": "Resize resource"
},
{
"id": 3,
"name": "Host Capacity",
"code": "hostCapacity",
"category": "utilization",
"title": "Add Capacity"
},
{
"id": 4,
"name": "Host Balancing",
"code": "hostBalancing",
"category": "utilization",
"title": "Balance Host"
},
{
"id": 5,
"name": "Datastore Capacity",
"code": "datastoreCapacity",
"category": "utilization",
"title": "Add Capacity"
},
{
"id": 6,
"name": "Reservation Recommendation",
"code": "reservations",
"category": "utilization",
"title": "Add Reservations"
}
]
}
This endpoint retrieves a list of discovery types.
HTTP Request
GET $serverUrl/api/guidance/types
Execute a Discovery
Use this command to execute a discovery.
curl -XPUT "$serverUrl/api/guidance/1/execute" \
-H "Authorization: BEARER $accessToken"
-H "Content-Type: application/json"
The above command returns JSON structured like this:
{
"success": true
}
HTTP Request
PUT $serverUrl/api/guidance/:id/execute
URL Parameters
| Parameter | Description |
|---|---|
| id | The ID of the discovery |
Ignore a Discovery
Use this command to ignore a discovery.
curl -XPUT "$serverUrl/api/guidance/1/ignore" \
-H "Authorization: BEARER $accessToken"
-H "Content-Type: application/json"
The above command returns JSON structured like this:
{
"success": true
}
HTTP Request
PUT $serverUrl/api/guidance/:id/ignore
URL Parameters
| Parameter | Description |
|---|---|
| id | The ID of the discovery |
Wiki
Morpheus provides a way to create and edit documentation in the form of wiki pages. Wiki pages use the markdown format and can be categorized to group them with other pages. Instances, apps, servers, clouds and groups can have their own wiki page associated to them.
Get All Wiki Pages
curl "$serverUrl/api/wiki/pages"
-H "Authorization: BEARER $accessToken"
The above command returns JSON structured like this:
{
"pages": [
{
"id": 1,
"name": "Home",
"urlName": "home",
"category": null,
"refId": null,
"refType": null,
"format": "markdown",
"content": "Welcome to the home page for this Morpheus wiki.",
"createdBy": {
"id": 1,
"username": "admin"
},
"updatedBy": {
"id": 1,
"username": "admin"
},
"dateCreated": "2019-06-27T16:55:59+0000",
"lastUpdated": "2019-06-27T16:55:59+0000"
},
{
"id": 2,
"name": "README",
"urlName": "info/readme",
"category": "info",
"refId": null,
"refType": null,
"format": "markdown",
"content": "A readme file for this local dev appliance.\nNeat.",
"createdBy": {
"id": 1,
"username": "admin"
},
"updatedBy": {
"id": 1,
"username": "admin"
},
"dateCreated": "2019-06-27T14:44:22+0000",
"lastUpdated": "2019-06-27T14:44:22+0000"
},
{
"id": 3,
"name": "My Group",
"urlName": "my-group",
"category": "groups",
"refId": 1,
"refType": "ComputeSite",
"format": "markdown",
"content": "#My Group\nThis is a test group",
"createdBy": {
"id": 1,
"username": "admin"
},
"updatedBy": {
"id": 1,
"username": "admin"
},
"dateCreated": "2019-06-28T01:41:45+0000",
"lastUpdated": "2019-06-28T01:41:45+0000"
}
],
"meta": {
"size": 2,
"total": 2,
"max": 25,
"offset": 0
}
}
This endpoint retrieves wiki pages associated with the account.
HTTP Request
GET $serverUrl/api/wiki/pages
Query Parameters
| Parameter | Default | Description |
|---|---|---|
| name | If specified will return an exact match on name or urlName | |
| phrase | If specified will return a partial match on name |
Get All Wiki Categories
curl "$serverUrl/api/wiki/categories"
-H "Authorization: BEARER $accessToken"
The above command returns JSON structured like this:
{
"categories": [
{
"name": "apps",
"pageCount": 1
},
{
"name": "clouds",
"pageCount": 1
},
{
"name": "groups",
"pageCount": 1
},
{
"name": "info",
"pageCount": 1
},
{
"name": "instances",
"pageCount": 2
},
{
"name": "servers",
"pageCount": 2
}
]
}
This endpoint retrieves all categories associated with the account. The results are not paginated. The categories returned are those of the found pages.
HTTP Request
GET $serverUrl/api/wiki/categories
Query Parameters
| Parameter | Default | Description |
|---|---|---|
| phrase | If specified will return a partial match on category name | |
| pagePhrase | If specified will return a partial match on page name |
Get a Specific Wiki Page
curl "$serverUrl/api/wiki/pages/2" \
-H "Authorization: BEARER $accessToken"
The above command returns JSON structured like this:
{
"page": {
"id": 1,
"name": "Home",
"urlName": "home",
"category": null,
"refId": null,
"refType": null,
"format": "markdown",
"content": "The home page for this wiki.",
"createdBy": {
"id": 1,
"username": "admin"
},
"updatedBy": {
"id": 1,
"username": "admin"
},
"dateCreated": "2019-06-27T16:55:59+0000",
"lastUpdated": "2019-06-27T16:55:59+0000"
}
}
This endpoint retrieves a specific wiki page.
HTTP Request
GET $serverUrl/api/wiki/pages/:id
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the Wiki Page |
Create a Wiki Page
curl -XPOST "$serverUrl/api/wiki/pages" \
-H "Authorization: BEARER $accessToken" \
-H "Content-Type: application/json" \
-d '{"page":{
"name": "Sample Doc",
"category": "info",
"content": "#Sample Doc\nA sample document in **markdown**."
}}'
The above command returns JSON structured like getting a single wiki page:
HTTP Request
POST $serverUrl/api/wiki/pages
JSON Page Parameters
| Parameter | Default | Description |
|---|---|---|
| name | A unique name scoped to your account for the wiki page. | |
| category | Optional category for grouping with other pages. | |
| content | The content of the page (markdown). |
Update a Wiki Page
curl -XPUT "$serverUrl/api/wiki/pages/4" \
-H "Authorization: BEARER $accessToken" \
-H "Content-Type: application/json" \
-d '{"page":{
"content": "#Sample Doc\nAn updated sample document in **markdown**.\nCheers!"
}}'
The above command returns JSON structured like getting a single wiki page
HTTP Request
PUT $serverUrl/api/wiki/pages/:id
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the Wiki Page |
JSON Page Parameters
| Parameter | Default | Description |
|---|---|---|
| name | A unique name scoped to your account for the wiki page. | |
| category | Optional category for grouping with other pages. | |
| content | The content of the page (markdown). |
Delete a Wiki Page
curl -XDELETE "$serverUrl/api/wiki/pages/1" \
-H "Authorization: BEARER $accessToken"
The above command returns JSON structured like getting a single wiki page
Will delete a Wiki Page from the system.
HTTP Request
DELETE $serverUrl/api/wiki/pages/:id
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the Wiki Page |
The above command returns JSON structure like this:
{
"success": true
}
Get a Wiki Page For Instance
curl "$serverUrl/api/instances/1/wiki" \
-H "Authorization: BEARER $accessToken"
The above command returns JSON structured like getting a single wiki page.
This endpoint retrieves the wiki page for an instance. If its page does not yet exist, the response is still 200 OK with a body like "page":null.
HTTP Request
GET $serverUrl/api/instances/:id/wiki
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the Instance |
Update a Wiki Page For Instance
curl -XPUT "$serverUrl/api/instances/1/wiki" \
-H "Authorization: BEARER $accessToken" \
-H "Content-Type: application/json" \
-d '{"page":{
"content": "Lots of good information about this instance."
}}'
The above command returns JSON structured like getting a single wiki page:
This endpoint updates the wiki page for an instance. The page will be created if it does not yet exist.
HTTP Request
PUT $serverUrl/api/instances/:id/wiki
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the Instance |
JSON Page Parameters
| Parameter | Default | Description |
|---|---|---|
| name | (instance name) | A unique name scoped to your account for the wiki page. |
| content | The content of the page (markdown). |
Get a Wiki Page For App
curl "$serverUrl/api/apps/1/wiki" \
-H "Authorization: BEARER $accessToken"
The above command returns JSON structured like getting a single wiki page.
This endpoint retrieves the wiki page for an app. If its page does not yet exist, the response is still 200 OK with a body like "page":null.
HTTP Request
GET $serverUrl/api/apps/:id/wiki
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the App |
Update a Wiki Page For App
curl -XPUT "$serverUrl/api/apps/1/wiki" \
-H "Authorization: BEARER $accessToken" \
-H "Content-Type: application/json" \
-d '{"page":{
"content": "Lots of good information about this app."
}}'
The above command returns JSON structured like getting a single wiki page:
This endpoint updates the wiki page for an app. The page will be created if it does not yet exist.
HTTP Request
PUT $serverUrl/api/apps/:id/wiki
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the App |
JSON Page Parameters
| Parameter | Default | Description |
|---|---|---|
| name | (app name) | A unique name scoped to your account for the wiki page. |
| content | The content of the page (markdown). |
Get a Wiki Page For Cluster
curl "$serverUrl/api/clusters/1/wiki" \
-H "Authorization: BEARER $accessToken"
The above command returns JSON structured like getting a single wiki page.
This endpoint retrieves the wiki page for a cluster. If its page does not yet exist, the response is still 200 OK with a body like "page":null.
HTTP Request
GET $serverUrl/api/clusters/:id/wiki
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the Cluster |
Update a Wiki Page For Cluster
curl -XPUT "$serverUrl/api/clusters/1/wiki" \
-H "Authorization: BEARER $accessToken" \
-H "Content-Type: application/json" \
-d '{"page":{
"content": "Lots of good information about this cluster."
}}'
The above command returns JSON structured like getting a single wiki page:
This endpoint updates the wiki page for a cluster. The page will be created if it does not yet exist.
HTTP Request
PUT $serverUrl/api/clusters/:id/wiki
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the Cluster |
JSON Page Parameters
| Parameter | Default | Description |
|---|---|---|
| name | (cluster name) | A unique name scoped to your account for the wiki page. |
| content | The content of the page (markdown). |
Get a Wiki Page For Server
curl "$serverUrl/api/servers/1/wiki" \
-H "Authorization: BEARER $accessToken"
The above command returns JSON structured like getting a single wiki page.
This endpoint retrieves the wiki page for a server. If its page does not yet exist, the response is still 200 OK with a body like "page":null.
HTTP Request
GET $serverUrl/api/servers/:id/wiki
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the Server |
Update a Wiki Page For Server
curl -XPUT "$serverUrl/api/servers/1/wiki" \
-H "Authorization: BEARER $accessToken" \
-H "Content-Type: application/json" \
-d '{"page":{
"content": "Lots of good information about this server."
}}'
The above command returns JSON structured like getting a single wiki page:
This endpoint updates the wiki page for a server. The page will be created if it does not yet exist.
HTTP Request
PUT $serverUrl/api/servers/:id/wiki
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the Server |
JSON Page Parameters
| Parameter | Default | Description |
|---|---|---|
| name | (server name) | A unique name scoped to your account for the wiki page. |
| content | The content of the page (markdown). |
Get a Wiki Page For Cloud
curl "$serverUrl/api/zones/1/wiki" \
-H "Authorization: BEARER $accessToken"
The above command returns JSON structured like getting a single wiki page.
This endpoint retrieves the wiki page for a cloud. If its page does not yet exist, the response is still 200 OK with a body like "page":null.
HTTP Request
GET $serverUrl/api/zones/:id/wiki
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the Cloud |
Update a Wiki Page For Cloud
curl -XPUT "$serverUrl/api/zones/1/wiki" \
-H "Authorization: BEARER $accessToken" \
-H "Content-Type: application/json" \
-d '{"page":{
"content": "Lots of good information about this cloud."
}}'
The above command returns JSON structured like getting a single wiki page:
This endpoint updates wiki page for a cloud. The page will be created if it does not yet exist.
HTTP Request
PUT $serverUrl/api/zones/:id/wiki
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the Cloud |
JSON Page Parameters
| Parameter | Default | Description |
|---|---|---|
| name | (cloud name) | A unique name scoped to your account for the wiki page. |
| content | The content of the page (markdown). |
Get a Wiki Page For Group
curl "$serverUrl/api/groups/1/wiki" \
-H "Authorization: BEARER $accessToken"
The above command returns JSON structured like getting a single wiki page.
This endpoint retrieves the wiki page for a group. If its page does not yet exist, the response is still 200 OK with a body like "page":null.
HTTP Request
GET $serverUrl/api/groups/:id/wiki
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the Group |
Update a Wiki Page For Group
curl -XPUT "$serverUrl/groups/1/wiki" \
-H "Authorization: BEARER $accessToken" \
-H "Content-Type: application/json" \
-d '{"page":{
"content": "Lots of good information about this group."
}}'
The above command returns JSON structured like getting a single wiki page:
This endpoint updates the wiki page for a group. The page will be created if it does not yet exist.
HTTP Request
PUT $serverUrl/api/groups/:id/wiki
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the Group |
JSON Page Parameters
| Parameter | Default | Description |
|---|---|---|
| name | (group name) | A unique name scoped to your account for the wiki page. |
| content | The content of the page (markdown). |
Budgets
Provides API interfaces for managing budgets.
Get All Budgets
curl "$serverUrl/api/budgets" \
-H "Authorization: BEARER $accessToken"
The above command returns JSON structured like this:
{
"budgets": [
{
"id": 1,
"name": "sample budget",
"description": "a yearly budget",
"account": {
"id": 1,
"name": "root"
},
"refScope": "account",
"refType": null,
"refId": null,
"refName": "root",
"interval": "year",
"period": "year",
"year": "2020",
"resourceType": "all",
"timezone": "America/New_York",
"startDate": "2020-01-01T05:00:00+0000",
"endDate": "2021-01-01T04:59:59+0000",
"active": true,
"enabled": true,
"rollover": false,
"costs": [
1000.0
],
"averageCost": 83.33333333333333,
"totalCost": 1000.0,
"currency": "USD",
"warningLimit": null,
"overLimit": null,
"externalId": null,
"internalId": null,
"createdById": 1,
"createdByName": "Admin",
"updatedById": null,
"updatedByName": null,
"dateCreated": "2020-01-03T17:40:08+0000",
"lastUpdated": "2020-01-03T17:40:08+0000"
},
{
"id": 2,
"name": "my budget",
"description": "99 per month",
"account": {
"id": 1,
"name": "root"
},
"refScope": "account",
"refType": null,
"refId": null,
"refName": "root",
"interval": "month",
"period": "year",
"year": "2020",
"resourceType": "all",
"timezone": "America/New_York",
"startDate": "2020-01-01T05:00:00+0000",
"endDate": "2021-01-01T04:59:59+0000",
"active": true,
"enabled": true,
"rollover": false,
"costs": [
99.0,
99.0,
99.0,
99.0,
99.0,
99.0,
99.0,
99.0,
99.0,
99.0,
99.0,
99.0,
],
"averageCost": 99.0,
"totalCost": 1188.0,
"currency": "USD",
"warningLimit": null,
"overLimit": null,
"externalId": null,
"internalId": null,
"createdById": 1,
"createdByName": "Admin",
"updatedById": null,
"updatedByName": null,
"dateCreated": "2020-01-03T17:37:51+0000",
"lastUpdated": "2020-01-03T17:37:51+0000"
},
{
"id": 3,
"name": "quarters",
"description": "Quarterly budget for tenant Acme",
"account": {
"id": 1,
"name": "root"
},
"refScope": "tenant",
"refType": "Account",
"refId": 47,
"refName": "Acme",
"interval": "quarter",
"period": "year",
"year": "2020",
"resourceType": "all",
"timezone": "America/New_York",
"startDate": "2020-01-01T05:00:00+0000",
"endDate": "2021-01-01T04:59:59+0000",
"active": true,
"enabled": true,
"rollover": false,
"costs": [
250.0,
250.0,
250.0,
500.0,
],
"averageCost": 312.5,
"totalCost": 1250.0,
"currency": "USD",
"warningLimit": null,
"overLimit": null,
"externalId": null,
"internalId": null,
"createdById": 1,
"createdByName": "James D",
"updatedById": null,
"updatedByName": null,
"dateCreated": "2020-01-02T02:54:34+0000",
"lastUpdated": "2020-01-03T17:43:52+0000"
}
],
"meta": {
"size": 3,
"total": 3,
"offset": 0,
"max": 25
}
}
This endpoint retrieves all budgets.
HTTP Request
GET $serverUrl/api/budgets
Query Parameters
| Parameter | Default | Description |
|---|---|---|
| max | 25 | Max number of results to return |
| offset | 0 | Offset of records you want to load |
| sort | name | Sort order |
| direction | asc | Sort direction, use 'desc' to reverse sort |
| phrase | Filter by matching name | |
| name | Filter by name |
Get a Specific Budget
curl "$serverUrl/api/budgets/1" \
-H "Authorization: BEARER $accessToken"
The above command returns JSON structured like this:
{
"success": true,
"budget": {
"id": 1,
"name": "sample budget",
"description": "a yearly budget",
"account": {
"id": 1,
"name": "root"
},
"refScope": "account",
"refType": null,
"refId": null,
"refName": "root",
"interval": "year",
"period": "year",
"year": "2020",
"resourceType": "all",
"timezone": "America/New_York",
"startDate": "2020-01-01T05:00:00+0000",
"endDate": "2021-01-01T04:59:59+0000",
"active": true,
"enabled": true,
"rollover": false,
"costs": [
1000.0
],
"averageCost": 83.33333333333333,
"totalCost": 1000.0,
"currency": "USD",
"warningLimit": null,
"overLimit": null,
"externalId": null,
"internalId": null,
"createdById": 1,
"createdByName": "Admin",
"updatedById": null,
"updatedByName": null,
"dateCreated": "2020-01-03T17:40:08+0000",
"lastUpdated": "2020-01-03T17:40:08+0000",
"stats": {
"averageCost": 83.33,
"totalCost": 1000.0,
"currency": "USD",
"conversionRate": 1,
"intervals": [
{
"index": 0,
"year": "Y1",
"shortYear": "Y1",
"budget": 1000.0,
"cost": 15.1016
}
],
"current": {
"estimatedCost": 15.1,
"lastCost": 15.1
}
}
}
}
This endpoint will retrieve a specific budget by id.
HTTP Request
GET $serverUrl/api/budgets/:id
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the budget |
Create a Budget
curl -XPOST "$serverUrl/api/budgets" \
-H "Authorization: BEARER $accessToken" \
-H "Content-Type: application/json" \
-d '{"budget":{
"name": "sample budget",
"year": "2020",
"interval": "year",
"scope": "account",
"costs": [1000]
}}'
The above command returns JSON structured like getting a single budget:
This endpoint creates a new budget.
HTTP Request
POST $serverUrl/api/budgets
JSON Parameters
The following parameters are passed inside an object named budget.
| Parameter | Default | Description |
|---|---|---|
| name | A unique name for the budget | |
| description | A description of the budget | |
| period | year | Budget period, year |
| year | 2020 | Budget period value, default is the current year. This can also be passed as custom along with a startDate and endDate. |
| startDate | Start Date for custom period budgets, should be the first of a month. eg. 2021-01-01 |
|
| endDate | End Date for custom period budgets, should be the last day of a month, and must be 12, 24, or 36 months after the start date. eg. 2021-12-31 |
|
| interval | year | Budget interval, year, quarter, month. |
| scope | The type of the scope for the budget, account, group, cloud, user. The default scope is account, which means the entire account. |
|
| scopeTenantId | The Tenant ID to scope to, for use with "scope"=tenant. |
|
| scopeGroupId | The Group ID to scope to, for use with "scope"=group. |
|
| scopeCloudId | The Cloud ID to scope to, for use with "scope"=cloud. |
|
| scopeUserId | The User ID to scope to, for use with "scope"=user. |
|
| costs | Array of budget cost amounts that varies in length by interval. For interval year use [1000]. For interval quarter use [200,200,200,400]. For interval month use [99,99,99,99,99,99,99,99,99,99,99,299] (other 10 months omitted). Custom budgets of more than one year may have more cost values. When creating a new schedule, the default cost for a given interval is 0 so be sure to specify a cost for every interval when creating a new budget. |
Updating a Budget
curl -XPUT "$serverUrl/api/budgets/:id" \
-H "Authorization: BEARER $accessToken" \
-H "Content-Type: application/json" \
-d '{"budget":{
"interval": "quarter",
"costs": [1000,1000,1000,2000]
}}'
The above command returns JSON structured like getting a single budget:
This endpoint updates a budget.
HTTP Request
PUT $serverUrl/api/budgets/:id
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the budget |
JSON Parameters
The following parameters are passed inside an object named budget.
| Parameter | Default | Description |
|---|---|---|
| name | A unique name for the budget | |
| description | A description of the budget | |
| period | year | Budget period, year |
| year | 2020 | Budget period value, default is the current year. This can also be passed as custom along with a startDate and endDate. |
| startDate | Start Date for custom period budgets, should be the first of a month. eg. 2021-01-01 |
|
| endDate | End Date for custom period budgets, should be the last day of a month, and must be exactly 12, 24, or 36 months after the start date. eg. 2021-12-31 |
|
| interval | year | Budget interval, year, quarter, month. |
| scope | The type of the scope for the budget, account, group, cloud, user. The default scope is account, which means the entire account. |
|
| scopeTenantId | The Tenant ID to scope to, for use with "scope"=tenant. |
|
| scopeGroupId | The Group ID to scope to, for use with "scope"=group. |
|
| scopeCloudId | The Cloud ID to scope to, for use with "scope"=cloud. |
|
| scopeUserId | The User ID to scope to, for use with "scope"=user. |
|
| costs | Array of budget cost amounts that varies in length by interval. For interval year use [1000]. For interval quarter use [200,200,200,400]. For interval month use [99,99,99,99,99,99,99,99,99,99,99,299] (other 10 months omitted). Custom budgets of more than one year may have more cost values. When creating a new schedule, the default cost for a given interval is 0 so be sure to specify a cost for every interval when creating a new budget. |
Delete a Budget
curl -XDELETE "$serverUrl/api/budgets/1" \
-H "Authorization: BEARER $accessToken"
The above command returns JSON Structured like this:
{
"success": true
}
This endpoint deletes a budget from the system.
HTTP Request
DELETE $serverUrl/api/budgets/:id
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the budget |
Invoices
Provides API interfaces for viewing account invoices.
Get All Invoices
curl "$serverUrl/api/invoices" \
-H "Authorization: BEARER $accessToken"
The above command returns JSON structured like this:
{
"invoices": [
{
"id": 11868,
"account": {
"id": 1,
"name": "root"
},
"group": {
"id": 1,
"name": "lonestar"
},
"cloud": {
"id": 39,
"name": "qa-amazon"
},
"instance": {
"id": 331,
"name": "nginx21"
},
"server": null,
"cluster": null,
"user": {
"id": 1,
"name": "admin"
},
"plan": {
"id": 1,
"name": "Amazon T2 Nano - 1 Core, 0.5GB Memory"
},
"tags": [
{
"id": 714462,
"name": "agency",
"value": "Lonestar"
},
{
"id": 714460,
"name": "hello",
"value": "world"
}
],
"project": {
"id": 2,
"name": "test",
"tags": {
"agency": "Lonestar"
}
},
"refType": "Instance",
"refId": 331,
"refName": "nginx21",
"refCategory": "vm",
"resourceId": null,
"resourceUuid": null,
"resourceType": null,
"resourceName": null,
"resourceExternalId": null,
"resourceInternalId": null,
"interval": "month",
"period": "202005",
"estimate": false,
"active": true,
"startDate": "2020-05-01T04:00:00+0000",
"endDate": "2020-06-01T03:59:59+0000",
"refStart": "2020-05-01T04:00:00+0000",
"refEnd": "2020-06-01T03:59:59+0000",
"estimatedComputePrice": 0.0,
"estimatedComputeCost": 0.0,
"estimatedMemoryPrice": 0.0,
"estimatedMemoryCost": 0.0,
"estimatedStoragePrice": 0.0,
"estimatedStorageCost": 0.0,
"estimatedNetworkPrice": 0.0,
"estimatedNetworkCost": 0.0,
"estimatedLicensePrice": 0.0,
"estimatedLicenseCost": 0.0,
"estimatedExtraPrice": 0.0,
"estimatedExtraCost": 0.0,
"estimatedTotalPrice": 6.250800024,
"estimatedTotalCost": 6.250800024,
"estimatedRunningPrice": 1.5038869430406268,
"estimatedRunningCost": 1.5038869430406268,
"estimatedCurrency": "USD",
"estimatedConversionRate": 1.0,
"actualComputePrice": 0.1709403426,
"actualComputeCost": 0.1709403426,
"actualMemoryPrice": 0.0,
"actualMemoryCost": 0.0,
"actualStoragePrice": 0.0,
"actualStorageCost": 0.0,
"actualNetworkPrice": 0.0,
"actualNetworkCost": 0.0,
"actualLicensePrice": 0.0,
"actualLicenseCost": 0.0,
"actualExtraPrice": 0.0,
"actualExtraCost": 0.0,
"actualTotalPrice": 0.7105014791842815,
"actualTotalCost": 0.7105014791842815,
"actualRunningPrice": 0.1709403426,
"actualRunningCost": 0.1709403426,
"actualCurrency": "USD",
"actualConversionRate": 1.0,
"computePrice": 0.1709403426,
"computeCost": 0.1709403426,
"memoryPrice": 0.0,
"memoryCost": 0.0,
"storagePrice": 0.0,
"storageCost": 0.0,
"networkPrice": 0.0,
"networkCost": 0.0,
"licensePrice": 0.0,
"licenseCost": 0.0,
"extraPrice": 0.0,
"extraCost": 0.0,
"totalPrice": 0.7105014791842815,
"totalCost": 0.7105014791842815,
"runningPrice": 0.1709403426,
"runningCost": 0.1709403426,
"currency": "USD",
"conversionRate": 1.0,
"costType": "actual",
"offTime": 0,
"powerState": "on",
"powerDate": "2020-05-01T04:00:00+0000",
"runningMultiplier": 0.2405911143,
"lastCostDate": "2020-05-08T14:59:59+0000",
"lastActualDate": "2020-05-08T14:59:59+0000",
"dateCreated": "2020-05-01T15:59:49+0000",
"lastUpdated": "2020-05-08T15:00:08+0000",
"lineItemCount": 0
}
],
"meta": {
"size": 25,
"total": 35021,
"offset": 0,
"max": 25
}
}
This endpoint retrieves a list of invoices for the specified parameters.
HTTP Request
GET $serverUrl/api/invoices
Query Parameters
| Parameter | Default | Description |
|---|---|---|
| max | 25 | Max number of results to return |
| offset | 0 | Offset of records you want to load |
| sort | startDate desc | Sort order |
| direction | asc | Sort direction, use 'desc' to reverse sort |
| phrase | If specified will return a partial match on refName | |
| name | If specified will return an exact match on refName | |
| startDate | Only return records with a startDate greater than or equal to the specified date. Format is YYYY-MM-DD. | |
| endDate | Only return records with an endDate less than or equal to the specified date. Format is YYYY-MM-DD. | |
| period | Only return records for period that matches with the specified value. This is an alternative to using startDate/endDate. Format is YYYY or YYYYMM. | |
| refType | If specified will return an exact match on refType. eg. ComputeSite (Group), ComputeZone (Cloud), ComputeServer (Host), Instance, Container, User. | |
| refId | If specified will return an exact match on refId | |
| refStatus | If specified, will filter on the associated StorageVolume status. eg. provisioned or unattached. This is only applicable when refType=StorageVolume. |
|
| zoneId | If specified will return an exact match on zone (cloud) ID | |
| siteId | If specified will return an exact match on site (group) ID | |
| instanceId | If specified will return an exact match on instance ID | |
| containerId | If specified will return an exact match on container ID | |
| serverId | If specified will return an exact match on server (host) ID | |
| userId | If specified will return an exact match on user ID | |
| projectId | If specified will return an exact match on project ID | |
| active | If specified will return an exact match on active flag. | |
| accountId | (own account) | Allows master tenant users to view invoices for another tenant. |
| includeLineItems | false | Pass true to include the list of lineItems for each invoice, only lineItemCount is returned by default. |
| includeTotals | false | Pass true to include the summed totals (cost/price values) for all the invoices found in the query. The returned property is called invoiceTotals. |
| tags | Filter by tags (metadata). This allows filtering by a tag name and value(s) like this tags.env=qa or tags.env=qa&tags.env=test which matches both: env=qa or env=test. |
Get a Specific Invoice
curl "$serverUrl/api/invoices/11868" \
-H "Authorization: BEARER $accessToken"
The above command returns JSON structured like this:
{
"invoice": {
"id": 11868,
"account": {
"id": 1,
"name": "root"
},
"group": {
"id": 1,
"name": "lonestar"
},
"cloud": {
"id": 39,
"name": "qa-amazon"
},
"instance": {
"id": 331,
"name": "nginx21"
},
"server": null,
"cluster": null,
"user": {
"id": 1,
"name": "admin"
},
"plan": {
"id": 1,
"name": "Amazon T2 Nano - 1 Core, 0.5GB Memory"
},
"tags": [
{
"id": 714462,
"name": "agency",
"value": "Lonestar"
},
{
"id": 714460,
"name": "hello",
"value": "world"
}
],
"project": {
"id": 2,
"name": "test",
"tags": {
"agency": "Lonestar"
}
},
"refType": "Instance",
"refId": 331,
"refName": "nginx21",
"refCategory": "vm",
"resourceId": null,
"resourceUuid": null,
"resourceType": null,
"resourceName": null,
"resourceExternalId": null,
"resourceInternalId": null,
"interval": "month",
"period": "202005",
"estimate": false,
"active": true,
"startDate": "2020-05-01T04:00:00+0000",
"endDate": "2020-06-01T03:59:59+0000",
"refStart": "2020-05-01T04:00:00+0000",
"refEnd": "2020-06-01T03:59:59+0000",
"estimatedComputePrice": 0.0,
"estimatedComputeCost": 0.0,
"estimatedMemoryPrice": 0.0,
"estimatedMemoryCost": 0.0,
"estimatedStoragePrice": 0.0,
"estimatedStorageCost": 0.0,
"estimatedNetworkPrice": 0.0,
"estimatedNetworkCost": 0.0,
"estimatedLicensePrice": 0.0,
"estimatedLicenseCost": 0.0,
"estimatedExtraPrice": 0.0,
"estimatedExtraCost": 0.0,
"estimatedTotalPrice": 6.250800024,
"estimatedTotalCost": 6.250800024,
"estimatedRunningPrice": 1.5038869430406268,
"estimatedRunningCost": 1.5038869430406268,
"estimatedCurrency": "USD",
"estimatedConversionRate": 1.0,
"actualComputePrice": 0.1709403426,
"actualComputeCost": 0.1709403426,
"actualMemoryPrice": 0.0,
"actualMemoryCost": 0.0,
"actualStoragePrice": 0.0,
"actualStorageCost": 0.0,
"actualNetworkPrice": 0.0,
"actualNetworkCost": 0.0,
"actualLicensePrice": 0.0,
"actualLicenseCost": 0.0,
"actualExtraPrice": 0.0,
"actualExtraCost": 0.0,
"actualTotalPrice": 0.7105014791842815,
"actualTotalCost": 0.7105014791842815,
"actualRunningPrice": 0.1709403426,
"actualRunningCost": 0.1709403426,
"actualCurrency": "USD",
"actualConversionRate": 1.0,
"computePrice": 0.1709403426,
"computeCost": 0.1709403426,
"memoryPrice": 0.0,
"memoryCost": 0.0,
"storagePrice": 0.0,
"storageCost": 0.0,
"networkPrice": 0.0,
"networkCost": 0.0,
"licensePrice": 0.0,
"licenseCost": 0.0,
"extraPrice": 0.0,
"extraCost": 0.0,
"totalPrice": 0.7105014791842815,
"totalCost": 0.7105014791842815,
"runningPrice": 0.1709403426,
"runningCost": 0.1709403426,
"currency": "USD",
"conversionRate": 1.0,
"costType": "actual",
"offTime": 0,
"powerState": "on",
"powerDate": "2020-05-01T04:00:00+0000",
"runningMultiplier": 0.2405911143,
"lastCostDate": "2020-05-08T14:59:59+0000",
"lastActualDate": "2020-05-08T14:59:59+0000",
"dateCreated": "2020-05-01T15:59:49+0000",
"lastUpdated": "2020-05-08T15:00:08+0000",
"lineItems": [
]
}
}
This endpoint retrieves a specific invoice.
HTTP Request
GET $serverUrl/api/invoices/:id
URL Parameters
| Parameter | Description |
|---|---|
| id | ID of the invoice |
Update Invoice Tags
curl -XPUT "$serverUrl/api/invoices/:id" \
-H "Authorization: BEARER $accessToken" \
-H "Content-Type: application/json" \
-d '{ "invoice": {
"addTags": [
{"name": "hello", "value": "world"}
],
"removeTags": [
{"name": "oldTag"}
]
}}'
The above command returns a similar JSON structure when submitting a GET request for a specific invoice
This endpoint allows updating the tags for a specific invoice. Invoice tags are automatically set to match the tags of the associated resource (ComputeServer/Instance/Container).
HTTP Request
PUT $serverUrl/api/invoices/:id
JSON Invoice Parameters
| Parameter | Default | Description |
|---|---|---|
| tags | Metadata tags, Array of objects having a name and value, this adds or updates the specified tags and removes any tags not specified. | |
| addTags | Add or update value of Metadata tags, Array of objects having a name and value | |
| removeTags | Remove Metadata tags, Array of objects having a name and an optional value. If value is passed, it must match to be removed. |
Get All Invoice Line Items
curl "$serverUrl/api/invoice-line-items" \
-H "Authorization: BEARER $accessToken"
The above command returns JSON structured like this:
{
"lineItems": [
{
"id": 3247,
"invoiceId": 12347,
"refType": "AccountResource",
"refId": 3,
"refName": "ocid1.instance.oc1.iad.abuwcljsdtocgl7wumoxflvd7725dobh3zk2s3rdmtnp5ixt2x7nc3awllda",
"refCategory": "invoice",
"startDate": "2020-05-09T22:00:00+0000",
"endDate": "2020-05-09T23:00:00+0000",
"itemId": "zmtWmBaN56GdFZq3ZeMhaTwKAXcECByQNvnlRA8yfsws/41naer2wamK1pC4gGVoxDjEHXVuDi3BHgE1epCBn5P5XcuFSmUd",
"itemType": null,
"itemName": "ocid1.instance.oc1.iad.abuwcljsdtocgl7wumoxflvd7725dobh3zk2s3rdmtnp5ixt2x7nc3awllda",
"itemDescription": null,
"productId": null,
"productCode": "B88514",
"productName": null,
"itemSeller": null,
"itemAction": null,
"externalId": "zmtWmBaN56GdFZq3ZeMhaTwKAXcECByQNvnlRA8yfsws/41naer2wamK1pC4gGVoxDjEHXVuDi3BHgE1epCBn5P5XcuFSmUd",
"rateId": null,
"rateClass": null,
"rateUnit": "0.0638",
"rateTerm": null,
"usageType": "Virtual Machine Standard - X7",
"usageCategory": "compute",
"itemUsage": 1.0,
"itemRate": 0.0,
"itemCost": 0.0638,
"itemPrice": 0.0638,
"itemTax": 0.0,
"itemTerm": null,
"taxType": null,
"dateCreated": "2020-05-12T02:29:54+0000",
"lastUpdated": "2020-05-12T02:29:54+0000"
},
{
"id": 3246,
"invoiceId": 12431,
"refType": "AccountResource",
"refId": 2139,
"refName": "ow-oraclecloud-1",
"refCategory": "invoice",
"startDate": "2020-05-09T21:00:00+0000",
"endDate": "2020-05-09T22:00:00+0000",
"itemId": "zmtWmBaN56GdFZq3ZeMhaTwKAXcECByQNvnlRA8yfsws/41naer2wamK1pC4gGVoxDjEHXVuDi39cmcwss32ZJP5XcuFSmUd",
"itemType": null,
"itemName": "ow-oraclecloud-1",
"itemDescription": null,
"productId": null,
"productCode": "B91962",
"productName": null,
"itemSeller": null,
"itemAction": null,
"externalId": "zmtWmBaN56GdFZq3ZeMhaTwKAXcECByQNvnlRA8yfsws/41naer2wamK1pC4gGVoxDjEHXVuDi39cmcwss32ZJP5XcuFSmUd",
"rateId": null,
"rateClass": null,
"rateUnit": "0.0017",
"rateTerm": null,
"usageType": "Block Volume - Performance Units",
"usageCategory": "storage",
"itemUsage": 0.672043008681,
"itemRate": 0.0,
"itemCost": 0.001142473117,
"itemPrice": 0.001142473117,
"itemTax": 0.0,
"itemTerm": null,
"taxType": null,
"dateCreated": "2020-05-11T08:47:06+0000",
"lastUpdated": "2020-05-11T08:47:06+0000"
}
],
"meta": {
"size": 2,
"total": 3269,
"offset": 22,
"max": 25
}
}
This endpoint retrieves all invoice line items for the specified parameters.
HTTP Request
GET $serverUrl/api/invoice-line-items
Query Parameters
| Parameter | Default | Description |
|---|---|---|
| max | 25 | Max number of results to return |
| offset | 0 | Offset of records you want to load |
| sort | startDate desc | Sort order |
| direction | asc | Sort direction, use 'desc' to reverse sort |
| phrase | If specified will return a partial match on refName | |
| name | If specified will return an exact match on refName | |
| startDate | Only return records with a startDate greater than or equal to the specified date. Format is YYYY-MM-DD. | |
| endDate | Only return records with an endDate less than or equal to the specified date. Format is YYYY-MM-DD. | |
| period | Only return records for period that matches with the specified value. This is an alternative to using startDate/endDate. Format is YYYY or YYYYMM. | |
| refType | If specified will return an exact match on refType. eg. ComputeSite (Group), ComputeZone (Cloud), ComputeServer (Host), Instance, Container, User. | |
| refId | If specified will return an exact match on refId | |
| zoneId | If specified will return an exact match on zone (cloud) ID | |
| siteId | If specified will return an exact match on site (group) ID | |
| instanceId | If specified will return an exact match on instance ID | |
| containerId | If specified will return an exact match on container ID | |
| serverId | If specified will return an exact match on server (host) ID | |
| userId | If specified will return an exact match on user ID | |
| projectId | If specified will return an exact match on project ID | |
| active | If specified will return an exact match on active flag. | |
| includeTotals | false | If true, invoiceTotals is returned containing sums of all the cost and prices for all the invoices found. |
| accountId | (own account) | Allows master tenant users to view invoices for another tenant. |
| includeTotals | false | Pass true to include the summed totals (cost/price values) for all the invoices found in the query. The returned property is called lineItemTotals. |
Get a Specific Invoice Line Item
curl "$serverUrl/api/invoice-line-items/678" \
-H "Authorization: BEARER $accessToken"
The above command returns JSON structured like this:
{
"lineItem": {
"id": 3246,
"invoiceId": 12431,
"refType": "AccountResource",
"refId": 2139,
"refName": "ow-oraclecloud-1",
"refCategory": "invoice",
"startDate": "2020-05-09T21:00:00+0000",
"endDate": "2020-05-09T22:00:00+0000",
"itemId": "zmtWmBaN56GdFZq3ZeMhaTwKAXcECByQNvnlRA8yfsws/41naer2wamK1pC4gGVoxDjEHXVuDi39cmcwss32ZJP5XcuFSmUd",
"itemType": null,
"itemName": "ow-oraclecloud-1",
"itemDescription": null,
"productId": null,
"productCode": "B91962",
"productName": null,
"itemSeller": null,
"itemAction": null,
"externalId": "zmtWmBaN56GdFZq3ZeMhaTwKAXcECByQNvnlRA8yfsws/41naer2wamK1pC4gGVoxDjEHXVuDi39cmcwss32ZJP5XcuFSmUd",
"rateId": null,
"rateClass": null,
"rateUnit": "0.0017",
"rateTerm": null,
"usageType": "Block Volume - Performance Units",
"usageCategory": "storage",
"itemUsage": 0.672043008681,
"itemRate": 0.0,
"itemCost": 0.001142473117,
"itemPrice": 0.001142473117,
"itemTax": 0.0,
"itemTerm": null,
"taxType": null,
"dateCreated": "2020-05-11T08:47:06+0000",
"lastUpdated": "2020-05-11T08:47:06+0000"
}
}
This endpoint retrieves a specific invoice.
HTTP Request
GET $serverUrl/api/invoice-line-items/:id
URL Parameters
| Parameter | Description |
|---|---|
| id | ID of the invoice line item |
Usage
Provides endpoints for viewing a list of usage for all your Containers and Servers. Morpheus keeps track of resource usage as the time periods that a resource was in use. A new usage record is created every time a resource is started or stopped. Each usage record includes the applied pricing and accumulated charges during the interval. Price is based on the assigned service plan.
This endpoint outputs usage data in the same format as the Billing api.
List Usages
curl "$serverUrl/api/usage"
-H "Authorization: BEARER $accessToken"
The above command returns JSON structured like this:
{
"usages": [
{
"id": 28791,
"zoneName": "aws",
"name": "example",
"planName": "Amazon T2 Nano - 1 Core, 0.5GB Memory",
"startDate": "2020-10-26T16:48:54Z",
"endDate": "2020-10-26T17:00:37Z",
"status": "running",
"price": 0.001668677955115256,
"costDetails": {
"refType": "container",
"refUUID": "9287ee06-75c6-4772-840c-fab7b2d668bd",
"refId": 938,
"startDate": "2020-10-26T16:48:54Z",
"endDate": "2020-10-26T17:00:37Z",
"cost": 0.001668677955115256,
"price": 0.001668677955115256,
"numUnits": 0.195410555555,
"unit": "hour",
"currency": "USD",
"usages": [
{
"cost": 0.001668677955115256,
"price": 0.001668677955115256,
"createdByUser": "Test User",
"createdByUserId": 127,
"siteId": 1,
"siteName": "mygroup",
"siteUUID": "9a18a409-e3b7-438b-b3d8-e393652f7c60",
"siteCode": null,
"currency": "USD",
"startDate": "2020-10-26T16:48:54Z",
"endDate": "2020-10-26T17:00:37Z",
"status": "running",
"tags": [],
"applicablePrices": [
{
"startDate": "2020-10-26T16:48:54Z",
"endDate": "2020-10-26T17:00:37Z",
"numUnits": 0.195410555555,
"cost": 0.001668677955115256,
"price": 0.001668677955115256,
"currency": "USD",
"prices": [
{
"type": "compute",
"pricePerUnit": 0.0069,
"costPerUnit": 0.0069,
"cost": 0.0013483328333295,
"price": 0.0013483328333295,
"quantity": null
},
{
"type": "storage",
"pricePerUnit": 0.000163934424,
"costPerUnit": 0.000163934424,
"cost": 3.203451686842893e-05,
"price": 3.203451686842893e-05,
"quantity": 10
}
]
}
],
"servicePlanId": 1,
"servicePlanName": "Amazon T2 Nano - 1 Core, 0.5GB Memory"
}
],
"numUsages": 1,
"totalUsages": 1,
"hasMoreUsages": false,
"foundPricing": true
}
}
],
"meta": {
"size": 25,
"total": 28133,
"offset": 0,
"max": 25
}
}
This endpoint retrieves a paginated list of usage records. The usages are scoped to only include resources you have access to.
HTTP Request
GET $serverUrl/api/usage
Query Parameters
| Parameter | Default | Description |
|---|---|---|
| max | 25 | Max number of results to return |
| offset | 0 | Offset of records you want to load |
| sort | startDate desc | Sort order, default is startDate desc |
| direction | asc | Sort direction: asc or desc |
| phrase | Filter by wildcard search of resource name | |
| type | Filter by a specific resource type: container, server, discoveredServer or loadBalancer | |
| startDate | Filter by startDate greater than or equal to a specified date | |
| endDate | Filter by endDate less than or equal to a specified date |
Billing
Provides API interfaces for viewing billing usage information by tenant, zone, instance or server. By default, usage is returned is from the beginning of the current month until now. The date range is parameterized but the end date cannot exceed the current date.
Billing By Tenant
curl "$serverUrl/api/billing/account" \
-H "Authorization: BEARER $accessToken"
The above command returns JSON structured like this:
{
"success": true,
"billingInfo": {
"accountId": 1,
"accountUUID": "775333da-8487-11ec-a8a3-0242ac120002",
"name": "Morpheus Data",
"startDate": "2017-02-01T07:00:00Z",
"endDate": "2017-02-22T23:03:13Z",
"priceUnit": "hour",
"price": 0,
"cost": 0,
"zones": [
{
"computeServers": [
{
"servers": [
{
"usages": [
]
}
]
}
],
"instances": [
{
"instances": [
{
"containers": {
"usages": [
]
}
}
]
}
]
}
]
}
}
Retrieves billing information for the requesting user's account.
HTTP Request
GET $serverUrl/api/billing/account
Query Parameters
| Parameter | Default | Description |
|---|---|---|
| startDate | Beginning of the current month | |
| endDate | Now | |
| includeUsages | true | Optional ability to suppress the usage records |
| maxUsages | null | Optional ability to limit the usages returned |
| offsetUsages | null | Optional ability to offset the usages returned, for use with maxUsages to paginate |
| includeComputeServers | true | Optional ability to exclude compute servers |
| includeInstances | true | Optional ability to exclude instances |
| includeDiscoveredServers | true | Optional ability to exclude discovered servers |
| includeLoadBalancers | true | Optional ability to exclude load balancers |
| includeVirtualImages | true | Optional ability to exclude virtual images |
| includeSnapshots | true | Optional ability to exclude snapshots |
Billing For a Specific Tenant
Will retrieve billing information for a specific tenant, if it is the current account or a sub account of the requesting user's account.
curl "$serverUrl/api/billing/account/1" \
-H "Authorization: BEARER $accessToken"
The above command returns JSON structured like this:
{
"success": true,
"billingInfo": {
"accountId": 1,
"accountUUID": "775333da-8487-11ec-a8a3-0242ac120002",
"name": "Morpheus Data",
"startDate": "2017-02-01T07:00:00Z",
"endDate": "2017-02-22T23:03:13Z",
"priceUnit": "hour",
"price": 0,
"cost": 0,
"zones": [
{
"computeServers": [
{
"servers": [
{
"usages": [
]
}
]
}
],
"instances": [
{
"instances": [
{
"containers": {
"usages": [
]
}
}
]
}
]
}
]
}
}
This endpoint will retrieve a specific account by id if the user has permission to access it.
HTTP Request
GET $serverUrl/api/billing/account/:id
Query Parameters
| Parameter | Default | Description |
|---|---|---|
| startDate | Beginning of the current month | |
| endDate | Now | |
| includeUsages | true | Optional ability to suppress the usage records |
| maxUsages | null | Optional ability to limit the usages returned |
| offsetUsages | null | Optional ability to offset the usages returned, for use with maxUsages to paginate |
| includeComputeServers | true | Optional ability to exclude compute servers |
| includeInstances | true | Optional ability to exclude instances |
| includeDiscoveredServers | true | Optional ability to exclude discovered servers |
| includeLoadBalancers | true | Optional ability to exclude load balancers |
| includeVirtualImages | true | Optional ability to exclude virtual images |
| includeSnapshots | true | Optional ability to exclude snapshots |
Billing For All Zones
curl "$serverUrl/api/billing/zones" \
-H "Authorization: BEARER $accessToken"
The above command returns JSON structured like this:
{
"success": true,
"billingInfo": {
"startDate": "2017-02-01T07:00:00Z",
"endDate": "2017-02-22T23:03:13Z",
"priceUnit": "hour",
"price": 0,
"cost": 0,
"zones": [
{
"computeServers": [
{
"servers": [
{
"usages": [
]
}
]
}
],
"instances": [
{
"instances": [
{
"containers": {
"usages": [
]
}
}
]
}
]
}
]
}
}
Retrieves billing information for all zones on the requestor's account.
HTTP Request
GET $serverUrl/api/billing/zones
Query Parameters
| Parameter | Default | Description |
|---|---|---|
| startDate | Beginning of the current month | |
| endDate | Now | |
| includeUsages | true | Optional ability to suppress the usage records |
| maxUsages | null | Optional ability to limit the usages returned |
| offsetUsages | null | Optional ability to offset the usages returned, for use with maxUsages to paginate |
| includeTenants | false | Optional ability to include all subtenant billing information when calling from a master tenant user |
| accountId | Optional ability to scope billing information to a subtenant when calling from a master tenant user. When specified with "includeTenants=true" accountId is ignored | |
| includeComputeServers | true | Optional ability to exclude compute servers |
| includeInstances | true | Optional ability to exclude instances |
| includeDiscoveredServers | true | Optional ability to exclude discovered servers |
| includeLoadBalancers | true | Optional ability to exclude load balancers |
| includeVirtualImages | true | Optional ability to exclude virtual images |
| includeSnapshots | true | Optional ability to exclude snapshots |
Billing For a Specific Zone
curl "$serverUrl/api/billing/zones/0801f6cd-4423-489f-859f-ee6ce24fd2ef" \
-H "Authorization: BEARER $accessToken"
The above command returns JSON structured like this:
{
"success": true,
"billingInfo": {
"zoneName": "",
"zoneId": 1,
"zoneUUID": "0801f6cd-4423-489f-859f-ee6ce24fd2ef",
"startDate": "2017-01-01T00:00:00Z",
"endDate": "2017-01-31T23:59:59Z",
"priceUnit": "hour",
"computeServers": {
"servers": [
{
"usages": [
]
}
]
},
"instances": {
"instances": [
{
"containers": [
{
"usages": [
{
"applicablePrices": [
]
}
]
}
]
}
]
}
}
}
Retrieves billing information for a specific zone in the requestor's account. Use zoneUUID whenever possible.
HTTP Request
GET $serverUrl/api/billing/zones/:zoneUUID|:id
Query Parameters
| Parameter | Default | Description |
|---|---|---|
| startDate | Beginning of the current month | |
| endDate | Now | |
| includeUsages | true | Optional ability to suppress the usage records |
| maxUsages | null | Optional ability to limit the usages returned |
| offsetUsages | null | Optional ability to offset the usages returned, for use with maxUsages to paginate |
| includeTenants | false | Optional ability to include all subtenant billing information when calling from a master tenant user |
| accountId | Optional ability to scope billing information to a subtenant when calling from a master tenant user. When specified with "includeTenants=true" accountId is ignored | |
| includeComputeServers | true | Optional ability to exclude compute servers |
| includeInstances | true | Optional ability to exclude instances |
| includeDiscoveredServers | true | Optional ability to exclude discovered servers |
| includeLoadBalancers | true | Optional ability to exclude load balancers |
| includeVirtualImages | true | Optional ability to exclude virtual images |
| includeSnapshots | true | Optional ability to exclude snapshots |
Billing For All Servers
curl "$serverUrl/api/billing/servers" \
-H "Authorization: BEARER $accessToken"
The above command returns JSON structured like this:
{
"success": true,
"billingInfo": {
"price": 0,
"cost": 0,
"startDate": "2017-03-01T07:00:00Z",
"endDate": "2017-03-09T22:03:28Z",
"servers": [
{
"refType": "computeServer",
"refUUID": "dca94ff0-2d5d-4e1e-985c-253e498140bf",
"refId": 1,
"startDate": "2017-01-01T00:00:00Z",
"endDate": "2017-01-31T23:59:59Z",
"cost": 0,
"price": 0,
"usages": [
],
"numUnits": 0,
"unit": "hour",
"name": "name"
}
]
}
}
Retrieves billing information for all servers (container hosts) on the requestor's account.
HTTP Request
GET $serverUrl/api/billing/servers
Query Parameters
| Parameter | Default | Description |
|---|---|---|
| startDate | Beginning of the current month | |
| endDate | Now | |
| includeUsages | true | Optional ability to suppress the usage records |
| maxUsages | null | Optional ability to limit the usages returned |
| offsetUsages | null | Optional ability to offset the usages returned, for use with maxUsages to paginate |
| includeTenants | false | Optional ability to include all subtenant billing information when calling from a master tenant user |
| accountId | Optional ability to scope billing information to a subtenant when calling from a master tenant user. When specified with "includeTenants=true" accountId is ignored |
Billing For a Specific Server
curl "$serverUrl/api/billing/servers/dca94ff0-2d5d-4e1e-985c-253e498140bf" \
-H "Authorization: BEARER $accessToken"
The above command returns JSON structured like this:
{
"success": true,
"billingInfo": {
"refType": "computeServer",
"refUUID": "dca94ff0-2d5d-4e1e-985c-253e498140bf",
"refId": 1,
"startDate": "2017-01-01T00:00:00Z",
"endDate": "2017-01-31T23:59:59Z",
"cost": 0,
"price": 0,
"usages": [
],
"numUnits": 0,
"unit": "hour",
"name": "name"
}
}
Retrieves billing information for a specific server (container host) in the requestor's account. Use refUUID whenever possible.
HTTP Request
GET $serverUrl/api/billing/servers/:refUUID|:id
Query Parameters
| Parameter | Default | Description |
|---|---|---|
| startDate | Beginning of the current month | |
| endDate | Now | |
| includeUsages | true | Optional ability to suppress the usage records |
| maxUsages | null | Optional ability to limit the usages returned |
| offsetUsages | null | Optional ability to offset the usages returned, for use with maxUsages to paginate |
| includeTenants | false | Optional ability to include all subtenant billing information when calling from a master tenant user |
| accountId | Optional ability to scope billing information to a subtenant when calling from a master tenant user. When specified with "includeTenants=true" accountId is ignored |
Billing For All Instances
curl "$serverUrl/api/billing/instances" \
-H "Authorization: BEARER $accessToken"
The above command returns JSON structured like this:
{
"success": true,
"billingInfo": {
"price": 0.0,
"cost": 0.0,
"startDate": "2017-01-01T00:00:00Z",
"endDate": "2017-01-31T23:59:59Z",
"instances": [
{
"containers": [
{
"usages": [
],
"numUnits": 0.0,
"unit": "hour",
"name": "name"
}
]
}
]
}
}
Retrieves billing information for all instances on the requestor's account.
HTTP Request
GET $serverUrl/api/billing/instances
Query Parameters
| Parameter | Default | Description |
|---|---|---|
| startDate | Beginning of the current month | |
| endDate | Now | |
| includeUsages | true | Optional ability to suppress the usage records |
| maxUsages | null | Optional ability to limit the usages returned |
| offsetUsages | null | Optional ability to offset the usages returned, for use with maxUsages to paginate |
| includeTenants | false | Optional ability to include all subtenant billing information when calling from a master tenant user |
| accountId | Optional ability to scope billing information to a subtenant when calling from a master tenant user. When specified with "includeTenants=true" accountId is ignored |
Billing For a Specific Instance
curl "$serverUrl/api/billing/instances/cf31b12d-9aa9-4394-8fad-12a0fbc2515e" \
-H "Authorization: BEARER $accessToken"
The above command returns JSON structured like this:
{
"success": true,
"billingInfo": {
"instanceId": 11,
"instanceUUID": "cf31b12d-9aa9-4394-8fad-12a0fbc2515e",
"startDate": "2017-01-01T00:00:00Z",
"endDate": "2017-01-31T23:59:59Z",
"name": "name",
"price": 0,
"cost": 0,
"containers": [
{
"usages": [
{
"applicablePrices": [
]
}
],
"numUnits": 0.0,
"unit": "hour",
"name": "name"
}
]
}
}
Retrieves billing information for a instance in the requestor's account. Use instanceUUID whenever possible.
HTTP Request
GET $serverUrl/api/billing/instances/:instanceUUID|:id
Query Parameters
| Parameter | Default | Description |
|---|---|---|
| startDate | Beginning of the current month | |
| endDate | Now | |
| includeUsages | true | Optional ability to suppress the usage records |
| maxUsages | null | Optional ability to limit the usages returned |
| offsetUsages | null | Optional ability to offset the usages returned, for use with maxUsages to paginate |
| includeTenants | false | Optional ability to include all subtenant billing information when calling from a master tenant user |
| accountId | Optional ability to scope billing information to a subtenant when calling from a master tenant user. When specified with "includeTenants=true" accountId is ignored |
Approvals
Provides API interfaces for managing approvals within Morpheus.
Get All Approvals
curl "$serverUrl/api/approvals" \
-H "Authorization: BEARER $accessToken"
The above command returns JSON structured like this:
{
"approvals": [
{
"id": 3,
"name": "APPROVAL-0000003",
"internalId": null,
"externalId": null,
"externalName": null,
"requestType": "Instance Approval",
"account": {
"id": 1,
"name": "Stubby Toes Inc."
},
"approver": {
"id": 1,
"name": "Stubby Toes Inc."
},
"accountIntegration": null,
"status": "1 approved",
"errorMessage": null,
"dateCreated": "2019-11-07T02:35:15+0000",
"lastUpdated": "2019-11-07T02:35:15+0000",
"requestBy": "Stubby Toes"
}
],
"meta": {
"size": 1,
"total": 1,
"max": 25,
"offset": 0
}
}
This endpoint retrieves all approvals.
HTTP Request
GET $serverUrl/api/approvals
Query Parameters
| Parameter | Default | Description |
|---|---|---|
| max | 25 | Max number of results to return |
| offset | 0 | Offset of records you want to load |
| sort | name | Sort order |
| direction | asc | Sort direction, use 'desc' to reverse sort |
| phrase | Name, externalName and requestBy filter, restricts query to only load approvals which contain the phrase specified | |
| name | Name filter, restricts query to only load approval matching name specified |
Get a Specific Approval
curl "$serverUrl/api/approvals/3" \
-H "Authorization: BEARER $accessToken"
The above command returns JSON structured like this:
{
"approval": {
"id": 3,
"name": "APPROVAL-0000003",
"internalId": null,
"externalId": null,
"externalName": null,
"requestType": "Instance Approval",
"account": {
"id": 1,
"name": "Stubby Toes Inc."
},
"approver": {
"id": 1,
"name": "Stubby Toes Inc."
},
"accountIntegration": null,
"status": "1 cancelled",
"errorMessage": null,
"dateCreated": "2019-11-07T02:35:15+0000",
"lastUpdated": "2019-11-07T02:35:15+0000",
"requestBy": "Stubby Toes",
"approvalItems": [
{
"id": 3,
"name": null,
"externalId": null,
"externalName": null,
"internalId": null,
"approvedBy": "Stubby Toes",
"deniedBy": "Stubby Toes",
"status": "cancelled",
"errorMessage": null,
"dateCreated": "2019-11-07T02:35:15+0000",
"lastUpdated": "2019-11-18T21:00:25+0000",
"dateApproved": "2019-11-18T19:56:30+0000",
"dateDenied": null,
"approval": {
"id": 3
},
"reference": {
"id": 3,
"type": "instance",
"name": "dans-ubuntu-3",
"displayName": "dans-ubuntu-3"
}
}
]
}
}
This endpoint retrieves a specific approval.
HTTP Request
GET $serverUrl/api/approvals/:id
URL Parameters
| Parameter | Description |
|---|---|
| id | ID of the approval |
Get a Specific Approval Item
curl "$serverUrl/api/approval-items/3" \
-H "Authorization: BEARER $accessToken"
The above command returns JSON structured like this:
{
"approvalItem": {
"id": 3,
"name": null,
"externalId": null,
"externalName": null,
"internalId": null,
"approvedBy": "Stubby Toes",
"deniedBy": "Stubby Toes",
"status": "cancelled",
"errorMessage": null,
"dateCreated": "2019-11-07T02:35:15+0000",
"lastUpdated": "2019-11-18T21:00:25+0000",
"dateApproved": "2019-11-18T19:56:30+0000",
"dateDenied": null,
"approval": {
"id": 3
},
"reference": {
"id": 3,
"type": "instance",
"name": "dans-ubuntu-3",
"displayName": "dans-ubuntu-3"
}
}
}
This endpoint retrieves a specific approval item
HTTP Request
GET $serverUrl/api/approval-items/:id
URL Parameters
| Parameter | Description |
|---|---|
| id | ID of the approval item |
Update an Approval Item
curl -XPUT "$serverUrl/api/approval-items/3/approve" \
-H "Authorization: BEARER $accessToken"
The above command returns JSON structured like this:
{
"success": true
}
This endpoint updates a specific approval item based upon specified action
HTTP Request
PUT $serverUrl/api/approval-items/:id/:action
URL Parameters
| Parameter | Required | Description |
|---|---|---|
| id | Y | ID of the approval item |
| action | Y | Approval item action [approve, deny, cancel] |
Activity
This endpoint provides data about activity with the Morpheus appliance. User activity and other Morpheus events can be seen here.
The most recent activity is returned by default.
Get All Activity
curl "$serverUrl/api/activity" \
-H "Authorization: BEARER $accessToken"
The above command returns JSON structured like this:
{
"activity": [
{
"_id": "ed970f86-c2bd-4ea2-8c3e-37494c8d8c67",
"success": false,
"activityType": "Alert",
"name": "test check",
"message": "Check has successfully been deleted",
"objectId": 239,
"objectType": "MonitorCheck",
"user": {
"id": 22,
"username": "tester"
},
"timestamp": "2019-10-23T19:31:54Z"
},
{
"_id": "247f122a-2dd6-4d92-a945-9e1fc35d8e51",
"success": false,
"activityType": "Monitoring",
"name": "dev-appliance",
"message": "Check has successfully been updated.",
"objectId": 238,
"objectType": "MonitorCheck",
"user": {
"id": 1,
"username": "root"
},
"ts": "2019-10-22T07:55:49Z"
},
{
"_id": "0276e1fc-214d-4cb3-bcf4-9ebda0b26542",
"success": false,
"activityType": "Monitoring",
"name": "dev-appliance",
"message": "Check successfully been created.",
"objectId": 238,
"objectType": "MonitorCheck",
"user": {
"id": 1,
"username": "root"
},
"ts": "2019-10-22T00:06:20Z"
},
{
"_id": "26976fe0-a722-4d20-9849-9405a95d0db9",
"success": true,
"activityType": "Admin",
"name": "julius",
"message": "User 'julius' updated. Password changed.",
"objectId": 96,
"objectType": "User",
"user": {
"id": 1,
"username": "root"
},
"ts": "2019-10-08T21:17:52Z"
}
]
}
HTTP Request
GET $serverUrl/api/activity
Query Parameters
| Parameter | Default | Description |
|---|---|---|
| max | 25 | Max number of results to return |
| offset | 0 | Offset of records you want to load |
| sort | name | Sort order |
| order | asc | Sort direction, use 'desc' to reverse sort |
| name | Filter by name | |
| phrase | Filter by wildcard search of name and description | |
| userId | Filter by User ID. | |
| tenantId | Filter by Tenant ID. Only available to the master account. | |
| timeframe | month | Filter by a timeframe. eg. today,yesterday,week,month,3months. |
| start | (1 month ago) | Filter by activity on or after a date(time) |
| end | (current time) | Filter by activity on or before a date(time) |
History
Provides API interfaces for viewing the process history for instances.
Get All Processes
curl "$serverUrl/api/processes" \
-H "Authorization: BEARER $accessToken"
The above command returns JSON structured like this:
{
"processes": [
{
"id": 250,
"accountId": 1,
"uniqueId": "cebc47ec-cb2f-417a-886e-dd60cf81db26",
"processType": {
"code": "provision",
"name": "provision"
},
"description": null,
"subType": null,
"subId": null,
"zoneId": 34,
"integrationId": null,
"instanceId": 238,
"containerId": 240,
"serverId": 601,
"containerName": "apachetest",
"displayName": "apachetest",
"timerCategory": "vmware",
"timerSubCategory": "28",
"status": "failed",
"reason": null,
"percent": 100.0,
"statusEta": 348246,
"message": null,
"output": null,
"error": null,
"startDate": "2018-09-28T19:10:56+0000",
"endDate": "2018-09-28T20:21:49+0000",
"duration": 4253127,
"dateCreated": "2018-09-28T19:10:56+0000",
"lastUpdated": "2018-09-28T20:21:49+0000",
"createdBy": {
"username": "admin",
"displayName": "Admin"
},
"updatedBy": {
"username": "admin",
"displayName": "Admin"
},
"events": [
]
}
],
"meta": {
"size": 1,
"total": 1,
"offset": 0,
"max": 25
}
}
This endpoint retrieves all processes.
HTTP Request
GET $serverUrl/api/processes
Query Parameters
| Parameter | Default | Description |
|---|---|---|
| phrase | If specified will return a partial match on displayName, message or output | |
| instanceId | Filter by instance id(s) | |
| containerId | Filter by container id(s) | |
| serverId | Filter by server id(s) | |
| zoneId | Filter by zone id(s) | |
| appId | Filter by app id(s) |
Get a Specific Process
curl "$serverUrl/api/processes/250" \
-H "Authorization: BEARER $accessToken"
The above command returns JSON structured like this:
{
"process": {
"id": 250,
"accountId": 1,
"uniqueId": "cebc47ec-cb2f-417a-886e-dd60cf81db26",
"processType": {
"code": "provision",
"name": "provision"
},
"description": null,
"subType": null,
"subId": null,
"zoneId": 34,
"integrationId": null,
"instanceId": 238,
"containerId": 240,
"serverId": 601,
"containerName": "apachetest",
"displayName": "apachetest",
"timerCategory": "vmware",
"timerSubCategory": "28",
"status": "failed",
"reason": null,
"percent": 100.0,
"statusEta": 348246,
"message": null,
"output": null,
"error": null,
"startDate": "2018-09-28T19:10:56+0000",
"endDate": "2018-09-28T20:21:49+0000",
"duration": 4253127,
"dateCreated": "2018-09-28T19:10:56+0000",
"lastUpdated": "2018-09-28T20:21:49+0000",
"createdBy": {
"username": "admin",
"displayName": "Admin"
},
"updatedBy": {
"username": "admin",
"displayName": "Admin"
},
"events": [
{
"id": 940,
"processId": 250,
"accountId": 1,
"uniqueId": "54bf6265-1e86-45b4-b1a7-d4b198b13c45",
"processType": {
"code": "provisionResources",
"name": "prepare resources"
},
"description": null,
"refType": "container",
"refId": 240,
"subType": null,
"subId": null,
"zoneId": 34,
"integrationId": null,
"instanceId": 238,
"containerId": 240,
"serverId": 601,
"containerName": "apachetest",
"displayName": "apachetest",
"status": "complete",
"reason": null,
"percent": 100.0,
"statusEta": 348246,
"message": null,
"output": null,
"error": null,
"startDate": "2018-09-28T19:10:56+0000",
"endDate": "2018-09-28T19:10:57+0000",
"duration": 921,
"dateCreated": "2018-09-28T19:10:56+0000",
"lastUpdated": "2018-09-28T19:10:57+0000",
"createdBy": {
"username": "admin",
"displayName": "Admin"
},
"updatedBy": {
"username": "admin",
"displayName": "Admin"
}
},
{
"id": 941,
"processId": 250,
"accountId": 1,
"uniqueId": "9a9791b7-0091-4ba7-be4d-e1586be3078c",
"processType": {
"code": "provisionImage",
"name": "prepare image"
},
"description": null,
"refType": "container",
"refId": 240,
"subType": null,
"subId": null,
"zoneId": 34,
"integrationId": null,
"instanceId": 238,
"containerId": 240,
"serverId": 601,
"containerName": "apachetest",
"displayName": "apachetest",
"status": "complete",
"reason": null,
"percent": 100.0,
"statusEta": 348246,
"message": null,
"output": null,
"error": null,
"startDate": "2018-09-28T19:10:57+0000",
"endDate": "2018-09-28T19:11:01+0000",
"duration": 3645,
"dateCreated": "2018-09-28T19:10:57+0000",
"lastUpdated": "2018-09-28T19:11:01+0000",
"createdBy": {
"username": "admin",
"displayName": "Admin"
},
"updatedBy": {
"username": "admin",
"displayName": "Admin"
}
},
{
"id": 942,
"processId": 250,
"accountId": 1,
"uniqueId": "f1905796-9387-4983-ae0d-0fee5bb81f56",
"processType": {
"code": "provisionConfig",
"name": "configure instance"
},
"description": null,
"refType": "container",
"refId": 240,
"subType": null,
"subId": null,
"zoneId": 34,
"integrationId": null,
"instanceId": 238,
"containerId": 240,
"serverId": 601,
"containerName": "apachetest",
"displayName": "apachetest",
"status": "complete",
"reason": null,
"percent": 100.0,
"statusEta": 348246,
"message": null,
"output": null,
"error": null,
"startDate": "2018-09-28T19:11:01+0000",
"endDate": "2018-09-28T19:11:01+0000",
"duration": 28,
"dateCreated": "2018-09-28T19:11:01+0000",
"lastUpdated": "2018-09-28T19:11:01+0000",
"createdBy": {
"username": "admin",
"displayName": "Admin"
},
"updatedBy": {
"username": "admin",
"displayName": "Admin"
}
},
{
"id": 943,
"processId": 250,
"accountId": 1,
"uniqueId": "599a0c2d-491c-4178-8b86-55b6d019d48c",
"processType": {
"code": "provisionDeploy",
"name": "deploy instance"
},
"description": null,
"refType": "container",
"refId": 240,
"subType": null,
"subId": null,
"zoneId": 34,
"integrationId": null,
"instanceId": 238,
"containerId": 240,
"serverId": 601,
"containerName": "apachetest",
"displayName": "apachetest",
"status": "complete",
"reason": null,
"percent": 100.0,
"statusEta": 348246,
"message": null,
"output": null,
"error": null,
"startDate": "2018-09-28T19:11:01+0000",
"endDate": "2018-09-28T19:11:33+0000",
"duration": 32219,
"dateCreated": "2018-09-28T19:11:01+0000",
"lastUpdated": "2018-09-28T19:11:33+0000",
"createdBy": {
"username": "admin",
"displayName": "Admin"
},
"updatedBy": {
"username": "admin",
"displayName": "Admin"
}
},
{
"id": 944,
"processId": 250,
"accountId": 1,
"uniqueId": "4f4088b0-7043-4a35-82c1-00456643beaa",
"processType": {
"code": "provisionResize",
"name": "resize instance"
},
"description": null,
"refType": "container",
"refId": 240,
"subType": null,
"subId": null,
"zoneId": 34,
"integrationId": null,
"instanceId": 238,
"containerId": 240,
"serverId": 601,
"containerName": "apachetest",
"displayName": "apachetest",
"status": "complete",
"reason": null,
"percent": 100.0,
"statusEta": 348246,
"message": null,
"output": null,
"error": null,
"startDate": "2018-09-28T19:11:33+0000",
"endDate": "2018-09-28T19:11:36+0000",
"duration": 2896,
"dateCreated": "2018-09-28T19:11:33+0000",
"lastUpdated": "2018-09-28T19:11:36+0000",
"createdBy": {
"username": "admin",
"displayName": "Admin"
},
"updatedBy": {
"username": "admin",
"displayName": "Admin"
}
},
{
"id": 945,
"processId": 250,
"accountId": 1,
"uniqueId": "10559e2a-6980-4443-afd4-37b7471492ba",
"processType": {
"code": "provisionCloudInit",
"name": "configure cloud init"
},
"description": null,
"refType": "container",
"refId": 240,
"subType": null,
"subId": null,
"zoneId": 34,
"integrationId": null,
"instanceId": 238,
"containerId": 240,
"serverId": 601,
"containerName": "apachetest",
"displayName": "apachetest",
"status": "complete",
"reason": null,
"percent": 100.0,
"statusEta": 348246,
"message": null,
"output": null,
"error": null,
"startDate": "2018-09-28T19:11:36+0000",
"endDate": "2018-09-28T19:11:42+0000",
"duration": 6152,
"dateCreated": "2018-09-28T19:11:36+0000",
"lastUpdated": "2018-09-28T19:11:42+0000",
"createdBy": {
"username": "admin",
"displayName": "Admin"
},
"updatedBy": {
"username": "admin",
"displayName": "Admin"
}
},
{
"id": 946,
"processId": 250,
"accountId": 1,
"uniqueId": "0081e523-bfea-4664-b582-d68076943a46",
"processType": {
"code": "provisionLaunch",
"name": "power on"
},
"description": null,
"refType": "container",
"refId": 240,
"subType": null,
"subId": null,
"zoneId": 34,
"integrationId": null,
"instanceId": 238,
"containerId": 240,
"serverId": 601,
"containerName": "apachetest",
"displayName": "apachetest",
"status": "complete",
"reason": null,
"percent": 100.0,
"statusEta": 348246,
"message": null,
"output": null,
"error": null,
"startDate": "2018-09-28T19:11:42+0000",
"endDate": "2018-09-28T19:11:45+0000",
"duration": 2549,
"dateCreated": "2018-09-28T19:11:42+0000",
"lastUpdated": "2018-09-28T19:11:45+0000",
"createdBy": {
"username": "admin",
"displayName": "Admin"
},
"updatedBy": {
"username": "admin",
"displayName": "Admin"
}
},
{
"id": 947,
"processId": 250,
"accountId": 1,
"uniqueId": "de66729e-9580-43b0-950c-f2769cd86790",
"processType": {
"code": "provisionNetwork",
"name": "network wait"
},
"description": null,
"refType": "container",
"refId": 240,
"subType": null,
"subId": null,
"zoneId": 34,
"integrationId": null,
"instanceId": 238,
"containerId": 240,
"serverId": 601,
"containerName": "apachetest",
"displayName": "apachetest",
"status": "failed",
"reason": null,
"percent": 100.0,
"statusEta": 348246,
"message": null,
"output": null,
"error": null,
"startDate": "2018-09-28T19:11:45+0000",
"endDate": "2018-09-28T20:21:49+0000",
"duration": 4204122,
"dateCreated": "2018-09-28T19:11:45+0000",
"lastUpdated": "2018-09-28T20:21:49+0000",
"createdBy": {
"username": "admin",
"displayName": "Admin"
},
"updatedBy": {
"username": "admin",
"displayName": "Admin"
}
}
]
}
}
This endpoint retrieves a specific process.
HTTP Request
GET $serverUrl/api/processes/:id
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the process |
Get a Specific Process Event
curl "$serverUrl/api/processes/events/940" \
-H "Authorization: BEARER $accessToken"
The above command returns JSON structured like this:
{
"processEvent": {
"id": 940,
"processId": 250,
"accountId": 1,
"uniqueId": "54bf6265-1e86-45b4-b1a7-d4b198b13c45",
"processType": {
"code": "provisionResources",
"name": "prepare resources"
},
"description": null,
"refType": "container",
"refId": 240,
"subType": null,
"subId": null,
"zoneId": 34,
"integrationId": null,
"instanceId": 238,
"containerId": 240,
"serverId": 601,
"containerName": "apachetest",
"displayName": "apachetest",
"status": "complete",
"reason": null,
"percent": 100.0,
"statusEta": 348246,
"message": null,
"output": null,
"error": null,
"startDate": "2018-09-28T19:10:56+0000",
"endDate": "2018-09-28T19:10:57+0000",
"duration": 921,
"dateCreated": "2018-09-28T19:10:56+0000",
"lastUpdated": "2018-09-28T19:10:57+0000",
"createdBy": {
"username": "admin",
"displayName": "Admin"
},
"updatedBy": {
"username": "admin",
"displayName": "Admin"
}
}
}
This endpoint retrieves a specific process event.
HTTP Request
GET $serverUrl/api/processes/events/:id
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the process event |
Provisioning
The Provisioning API endpoints provide management of Instances, Apps, Automation and Deployments.
Morpheus supports a diverse set of cloud APIS for provisioning compute and services. In order to facilitate some of these capabilities and preserve some of the diverse sets of feature sets across these plaforms it is necessary to provide a means to dynamicaly specifying provisioning options depending on what is being provisioned. Morpheus calls these ProvisionType. Each InstanceTypeLayout that can be provisioned has a correlating ProvisionType and each CloudType (aka ZoneType) has a list of supported provision types it is capable of provisioning. This record contains optionTypes (see section on optionTypes for specifics on how to parse this data) as well as information for building out network parameters and storage parameters by listing different storage type information.
Provision Types
Fetch the list of available provision types.
curl "$serverUrl/api/provision-types"
-H "Authorization: BEARER $accessToken"
The above command returns JSON structured like this
{
"provisionTypes": [
{
"id": 9,
"name": "Amazon",
"description": null,
"code": "amazon",
"aclEnabled": false,
"multiTenant": false,
"managed": true,
"hostNetwork": true,
"customSupported": false,
"mapPorts": false,
"exportServer": null,
"viewSet": "amazonCustom",
"serverType": "ami",
"hostType": "vm",
"addVolumes": true,
"hasDatastore": false,
"hasNetworks": null,
"maxNetworks": null,
"customizeVolume": true,
"rootDiskCustomizable": true,
"lvmSupported": true,
"hostDiskMode": "lvm",
"minDisk": 0,
"maxDisk": null,
"resizeCopiesVolumes": true,
"optionTypes": [
{
"name": "subnet",
"description": null,
"fieldName": "subnetId",
"fieldLabel": "Subnet",
"fieldContext": "config",
"fieldAddOn": null,
"placeHolder": null,
"helpBlock": "",
"defaultValue": null,
"optionSource": "amazonSubnet",
"type": "select",
"advanced": false,
"required": true,
"editable": false,
"config": [],
"displayOrder": 100
},
{
"name": "security group",
"description": null,
"fieldName": "securityId",
"fieldLabel": "Security Group",
"fieldContext": "config",
"fieldAddOn": null,
"placeHolder": null,
"helpBlock": "",
"defaultValue": null,
"optionSource": "amazonSecurityGroup",
"type": "select",
"advanced": false,
"required": true,
"editable": false,
"config": [],
"displayOrder": 101
},
{
"name": "public key",
"description": null,
"fieldName": "publicKeyId",
"fieldLabel": "Public Key",
"fieldContext": "config",
"fieldAddOn": null,
"placeHolder": null,
"helpBlock": "",
"defaultValue": null,
"optionSource": "keyPairs",
"type": "select",
"advanced": false,
"required": false,
"editable": false,
"config": [],
"displayOrder": 9
}
],
"customOptionTypes": [],
"networkTypes": [],
"storageTypes": [
{
"id": 7,
"code": "amazon-sc1",
"name": "sc1",
"displayOrder": 4,
"defaultType": false,
"customLabel": true,
"customSize": true,
"customSizeOptions": null
},
{
"id": 4,
"code": "amazon-io1",
"name": "io1",
"displayOrder": 2,
"defaultType": false,
"customLabel": true,
"customSize": true,
"customSizeOptions": null
},
{
"id": 5,
"code": "amazon-gp2",
"name": "gp2",
"displayOrder": 1,
"defaultType": true,
"customLabel": true,
"customSize": true,
"customSizeOptions": null
},
{
"id": 6,
"code": "amazon-st1",
"name": "st1",
"displayOrder": 3,
"defaultType": false,
"customLabel": true,
"customSize": true,
"customSizeOptions": null
}
],
"rootStorageTypes": [
{
"id": 7,
"code": "amazon-sc1",
"name": "sc1",
"displayOrder": 4,
"defaultType": false,
"customLabel": true,
"customSize": true,
"customSizeOptions": null
},
{
"id": 4,
"code": "amazon-io1",
"name": "io1",
"displayOrder": 2,
"defaultType": false,
"customLabel": true,
"customSize": true,
"customSizeOptions": null
},
{
"id": 5,
"code": "amazon-gp2",
"name": "gp2",
"displayOrder": 1,
"defaultType": true,
"customLabel": true,
"customSize": true,
"customSizeOptions": null
},
{
"id": 6,
"code": "amazon-st1",
"name": "st1",
"displayOrder": 3,
"defaultType": false,
"customLabel": true,
"customSize": true,
"customSizeOptions": null
}
],
"controllerTypes": []
}
]
}
HTTP Request
GET $serverUrl/api/provision-types
Query Parameters
| Parameter | Default | Description |
|---|---|---|
| max | 25 | Max number of results to return |
| offset | 0 | Offset of records you want to load |
| sort | name | Sort order |
| direction | asc | Sort direction, use 'desc' to reverse sort |
| phrase | Name and code, restricts query to only load provision types which contain the phrase specified | |
| name | Name filter, restricts query to only load type matching name specified | |
| code | Code filter, restricts query to only load type matching code specified |
Get Specific Provision Type
curl "$serverUrl/api/provision-types/9"
-H "Authorization: BEARER $accessToken"
The above command returns JSON structured like this
{
"success": true,
"provisionType": {
"id": 9,
"name": "Amazon",
"description": null,
"code": "amazon",
"aclEnabled": false,
"multiTenant": false,
"managed": true,
"hostNetwork": true,
"customSupported": false,
"mapPorts": false,
"exportServer": null,
"viewSet": "amazonCustom",
"serverType": "ami",
"hostType": "vm",
"addVolumes": true,
"hasDatastore": false,
"hasNetworks": null,
"maxNetworks": null,
"customizeVolume": true,
"rootDiskCustomizable": true,
"lvmSupported": true,
"hostDiskMode": "lvm",
"minDisk": 0,
"maxDisk": null,
"resizeCopiesVolumes": true,
"optionTypes": [
{
"name": "subnet",
"description": null,
"fieldName": "subnetId",
"fieldLabel": "Subnet",
"fieldContext": "config",
"fieldAddOn": null,
"placeHolder": null,
"helpBlock": "",
"defaultValue": null,
"optionSource": "amazonSubnet",
"type": "select",
"advanced": false,
"required": true,
"editable": false,
"config": [],
"displayOrder": 100
},
{
"name": "security group",
"description": null,
"fieldName": "securityId",
"fieldLabel": "Security Group",
"fieldContext": "config",
"fieldAddOn": null,
"placeHolder": null,
"helpBlock": "",
"defaultValue": null,
"optionSource": "amazonSecurityGroup",
"type": "select",
"advanced": false,
"required": true,
"editable": false,
"config": [],
"displayOrder": 101
},
{
"name": "public key",
"description": null,
"fieldName": "publicKeyId",
"fieldLabel": "Public Key",
"fieldContext": "config",
"fieldAddOn": null,
"placeHolder": null,
"helpBlock": "",
"defaultValue": null,
"optionSource": "keyPairs",
"type": "select",
"advanced": false,
"required": false,
"editable": false,
"config": [],
"displayOrder": 9
}
],
"customOptionTypes": [],
"networkTypes": [],
"storageTypes": [
{
"id": 7,
"code": "amazon-sc1",
"name": "sc1",
"displayOrder": 4,
"defaultType": false,
"customLabel": true,
"customSize": true,
"customSizeOptions": null
},
{
"id": 4,
"code": "amazon-io1",
"name": "io1",
"displayOrder": 2,
"defaultType": false,
"customLabel": true,
"customSize": true,
"customSizeOptions": null
},
{
"id": 5,
"code": "amazon-gp2",
"name": "gp2",
"displayOrder": 1,
"defaultType": true,
"customLabel": true,
"customSize": true,
"customSizeOptions": null
},
{
"id": 6,
"code": "amazon-st1",
"name": "st1",
"displayOrder": 3,
"defaultType": false,
"customLabel": true,
"customSize": true,
"customSizeOptions": null
}
],
"rootStorageTypes": [
{
"id": 7,
"code": "amazon-sc1",
"name": "sc1",
"displayOrder": 4,
"defaultType": false,
"customLabel": true,
"customSize": true,
"customSizeOptions": null
},
{
"id": 4,
"code": "amazon-io1",
"name": "io1",
"displayOrder": 2,
"defaultType": false,
"customLabel": true,
"customSize": true,
"customSizeOptions": null
},
{
"id": 5,
"code": "amazon-gp2",
"name": "gp2",
"displayOrder": 1,
"defaultType": true,
"customLabel": true,
"customSize": true,
"customSizeOptions": null
},
{
"id": 6,
"code": "amazon-st1",
"name": "st1",
"displayOrder": 3,
"defaultType": false,
"customLabel": true,
"customSize": true,
"customSizeOptions": null
}
],
"controllerTypes": []
}
}
HTTP Request
GET $serverUrl/api/provision-types/:id
Instances
Instances are sets of containers or vms (Morpheus API represents a vm as a container attached to a server) of various types that can be provisioned across the Morpheus stack and offer a wide range of services. MySQL, Redis, ElasticSearch, PostgreSQL, Tomcat, nginx, Confluence, Jenkins, and more. There are a few important concept differentiators between what Morpheus calls an instance and what amazon calls an instance. In Morpheus an isntance can represent many vms or containers that are of a set. For example. If you wanted to spin up a Mongo sharded replicaset, that requires 7 virtual machines or 7 docker containers. Morpheus represents this as a singular instance with a specified layout and then represents all the associated services running within that instance as containers. If, a container record is a docker container then the serverId it belongs to is representative of the Docker Host it was provisioned onto. If the container is a virtual machine then the serverId represents the compute resource it was provisioned onto, (i.e. the virtual machine).
Get All Instances
curl "$serverUrl/api/instances?max=3"
-H "Authorization: BEARER $accessToken"
The above command returns JSON structured like this:
{
"instances": [
{
"id": 1530,
"accountId": 1,
"instanceType": {
"id": 35,
"code": "ubuntu",
"category": "os",
"name": "Ubuntu"
},
"group": {
"id": 3,
"name": "Demo"
},
"cloud": {
"id": 6,
"name": "San Mateo VMware"
},
"containers": [
1798
],
"servers": [
2
],
"connectionInfo": [
{
"ip": "192.168.162.59",
"port": 22
}
],
"layout": {
"id": 105
},
"plan": {
"id": 12,
"code": "vm-2048"
},
"name": "ah-San Mateo VMware-ubuntu",
"description": null,
"instanceVersion": null,
"dateCreated": "2017-01-31T21:30:49+0000",
"lastUpdated": "2017-02-07T22:58:26+0000",
"hostName": "ah-San-Mateo-VMware-ubuntu",
"domainName": null,
"environmentPrefix": null,
"firewallEnabled": true,
"networkLevel": "container",
"autoScale": false,
"instanceContext": "production",
"currentDeployId": null,
"status": "running",
"statusMessage": null,
"errorMessage": null,
"statusDate": "2017-01-31T21:34:07+0000",
"statusPercent": null,
"statusEta": null,
"userStatus": null,
"createdBy": {
"id": 38
}
},
{
"id": 1653,
"accountId": 1,
"instanceType": {
"id": 35,
"code": "ubuntu",
"category": "os",
"name": "Ubuntu"
},
"group": {
"id": 3,
"name": "Demo"
},
"cloud": {
"id": 6,
"name": "San Mateo VMware"
},
"containers": [
1945
],
"servers": [
2
],
"connectionInfo": [
{
"ip": "192.168.163.55",
"port": 22
}
],
"layout": {
"id": 105
},
"plan": {
"id": 11,
"code": "vm-1024"
},
"name": "ah-San Mateo VMware-ubuntu-PDNStest",
"description": null,
"instanceVersion": null,
"dateCreated": "2017-02-10T14:27:42+0000",
"lastUpdated": "2017-02-10T14:31:19+0000",
"hostName": "ah-san-mateo-vmware-ubuntu-pdnstest",
"domainName": null,
"environmentPrefix": null,
"firewallEnabled": true,
"networkLevel": "container",
"autoScale": false,
"instanceContext": "dev",
"currentDeployId": null,
"status": "running",
"statusMessage": null,
"errorMessage": null,
"statusDate": "2017-02-10T14:30:43+0000",
"statusPercent": null,
"statusEta": null,
"userStatus": null,
"createdBy": {
"id": 38
}
},
{
"id": 1624,
"accountId": 1,
"instanceType": {
"id": 21,
"code": "apache",
"category": "web",
"name": "Apache"
},
"group": {
"id": 163,
"name": "snow-approvals"
},
"cloud": {
"id": 6,
"name": "San Mateo VMware"
},
"containers": [
1912
],
"servers": [
3
],
"connectionInfo": [
{
"ip": "192.168.163.28",
"port": 10009
}
],
"layout": {
"id": 48
},
"plan": {
"id": 3,
"code": "container-256"
},
"name": "approval-snow-test",
"description": null,
"instanceVersion": null,
"dateCreated": "2017-02-09T06:45:30+0000",
"lastUpdated": "2017-02-09T06:53:20+0000",
"hostName": "approval-snow-test",
"domainName": null,
"environmentPrefix": null,
"firewallEnabled": true,
"networkLevel": "container",
"autoScale": false,
"instanceContext": null,
"currentDeployId": null,
"status": "running",
"statusMessage": null,
"errorMessage": null,
"statusDate": "2017-02-09T06:53:20+0000",
"statusPercent": null,
"statusEta": null,
"userStatus": null,
"owner": {
"id": 1,
"username": "admin"
}
}
],
"stats": {
"1530": {
"usedStorage": 6776664064,
"maxStorage": 21067075584,
"usedMemory": 1909739520,
"maxMemory": 2098315264,
"usedCpu": 1.0926682792
},
"1653": {
"usedStorage": 2662801408,
"maxStorage": 10499452928,
"usedMemory": 935444480,
"maxMemory": 1041350656,
"usedCpu": 0.1501000667
},
"1624": {
"usedStorage": 4829184,
"maxStorage": 3103539200,
"usedMemory": 9113600,
"maxMemory": 268435456,
"usedCpu": 0
}
},
"loadBalancers": [],
"meta": {
"offset": 0,
"max": 25,
"size": 3,
"total": 21
}
}
This endpoint retrieves a paginated list of instances.
HTTP Request
GET $serverUrl/api/instances
Query Parameters
| Parameter | Default | Description |
|---|---|---|
| max | 25 | Max number of results to return |
| offset | 0 | Offset of records you want to load |
| name | Filter by name | |
| phrase | Filter by wildcard search of name and description | |
| instanceType | Filter by instance type code | |
| lastUpdated | Date filter, restricts query to only load instances updated timestamp is more recent or equal to the date specified | |
| createdBy | Filter by Created By (User) ID. Accepts multiple values. | |
| agentInstalled | Filter instances by if agent is installed or not on the associated servers. | |
| status | Filter by instance status | |
| environment | Filter by environment code | |
| showDeleted | false | If true, includes instances in pending removal status. |
| deleted | If true, only instances in pending removal status are returned. | |
| expireDate | Filter by expireDate less than equal to specified date | |
| expireDateMin | Filter expireDate greater than or equal to the specified date | |
| expireDays | Filter by expireDays less than or equal to the specified value | |
| expireDaysMin | Filter by expireDays greater than or equal to the specified value | |
| shutdownDate | Filter by shutdownDate less than equal to the specified date | |
| shutdownDateMin | Filter by shutdownDate greater than or equal to the specified date | |
| shutdownDays | Filter by shutdownDays less than or equal to the specified value | |
| shutdownDaysMin | Filter by shutdownDays greater than or equal to the specified value | |
| labels | Filter by label(s). | |
| tags | Filter by tags (metadata). This allows filtering by arbitrary tag names and values like this tags.foo=bar. |
|
| metadata | Alias for tags. |
|
| details | false | Include details=true to return more details about the instance, ie. containerDetails. Available in api version 5.2.8/5.3.2. |
Get a Specific Instance
curl "$serverUrl/api/instances/1216" \
-H "Authorization: BEARER $accessToken"
The above command returns JSON structured like this:
{
"instance": {
"id": 392,
"uuid": "6ccf1fa9-da1f-4318-841e-7bf30c4522c6",
"accountId": 1,
"tenant": {
"id": 1,
"name": "Morpheus Data"
},
"instanceType": {
"id": 6,
"code": "apache",
"category": "web",
"name": "Apache"
},
"group": {
"id": 1,
"name": "dev"
},
"cloud": {
"id": 39,
"name": "amazon"
},
"containers": [
945
],
"servers": [
4002
],
"connectionInfo": [
{
"ip": "10.100.1.8",
"port": 80
}
],
"layout": {
"id": 31,
"name": "Amazon Apache on Ubuntu 14.04",
"provisionTypeCode": "amazon"
},
"plan": {
"id": 1,
"code": "amazon-t2.nano",
"name": "Amazon T2 Nano - 1 Core, 0.5GB Memory"
},
"name": "sa-apache-1",
"description": "new description",
"environment": null,
"config": {
"createUser": true,
"isEC2": false,
"isVpcSelectable": true,
"noAgent": null,
"availabilityId": null,
"securityId": null,
"publicIpType": "subnet",
"instanceProfile": null,
"resourcePoolId": "173",
"poolProviderType": null,
"name": "${userInitials}-apache-${sequence}",
"hostName": "${userInitials}-apache-${sequence}",
"instanceType": {
"code": null
},
"site": {
"id": 1,
"name": "dev"
},
"environmentPrefix": null,
"layout": {
"id": 31,
"code": "apache-amazon-2.4-single"
},
"type": "apache",
"memoryDisplay": "MB",
"securityGroups": [
{
"id": "sg-21dd8144"
}
],
"customOptions": {
"isPrimary": "on",
"inventoryName": "DB12"
},
"createBackup": true,
"backup": {
"createBackup": true,
"jobAction": "new",
"jobRetentionCount": "3",
"veeamManagedServer": "",
"backupRepository": 1,
"jobSchedule": 2,
"target": 37006
},
"layoutSize": 1,
"lbInstances": [
]
},
"configGroup": null,
"configId": null,
"configRole": null,
"volumes": [
{
"controllerId": null,
"datastoreId": null,
"displayOrder": 0,
"id": 177034,
"maxIOPS": null,
"maxStorage": 10737418240,
"name": "root",
"shortName": "root",
"resizeable": true,
"rootVolume": true,
"size": 10,
"storageType": 5,
"unitNumber": null,
"controllerMountPoint": null
}
],
"controllers": [
],
"interfaces": [
{
"id": "365",
"network": {
"id": 365,
"group": null,
"subnet": null,
"dhcpServer": true,
"name": "labs1",
"pool": null
},
"ipAddress": null,
"networkInterfaceTypeId": null,
"ipMode": ""
}
],
"customOptions": {
"isPrimary": "on",
"inventoryName": "DB12"
},
"instanceVersion": "2.4",
"labels": [
"foo",
"bar"
],
"tags": [
{
"id": 70539,
"name": "Morpheus Id",
"value": "945"
},
{
"id": 70541,
"name": "Morpheus Instance Id",
"value": "392"
},
{
"id": 70538,
"name": "Morpheus Labels",
"value": "foo,bar"
},
{
"id": 70540,
"name": "Morpheus Server Id",
"value": "4002"
},
{
"id": 70530,
"name": "abc",
"value": "123"
}
],
"evars": [
{
"name": "APACHE_IP",
"value": "10.100.1.8",
"export": true,
"masked": false
},
{
"name": "APACHE_HOST",
"value": "container945",
"export": true,
"masked": false
},
{
"name": "APACHE_PORT_HTTP",
"value": 80,
"export": true,
"masked": false
},
{
"name": "APACHE_PORT_80_TCP_PORT",
"value": 80,
"export": true,
"masked": false
},
{
"name": "APACHE_PORT_80_TCP_PROTO",
"value": "tcp",
"export": true,
"masked": false
},
{
"name": "APACHE_PORT_80_TCP_ADDR",
"value": "10.100.1.8",
"export": true,
"masked": false
},
{
"name": "APACHE_PORT_80_TCP",
"value": "tcp://10.100.1.8:80",
"export": true,
"masked": false
},
{
"name": "APACHE_PORT_HTTPS",
"value": 443,
"export": true,
"masked": false
},
{
"name": "APACHE_PORT_443_TCP_PORT",
"value": 443,
"export": true,
"masked": false
},
{
"name": "APACHE_PORT_443_TCP_PROTO",
"value": "tcp",
"export": true,
"masked": false
},
{
"name": "APACHE_PORT_443_TCP_ADDR",
"value": "10.100.1.8",
"export": true,
"masked": false
},
{
"name": "APACHE_PORT_443_TCP",
"value": "tcp://10.100.1.8:443",
"export": true,
"masked": false
}
],
"maxMemory": 536870912,
"maxStorage": 10737418240,
"maxCores": 1,
"coresPerSocket": 1,
"maxCpu": 1,
"hourlyCost": 0.0086816667,
"hourlyPrice": 0.0086816667,
"instancePrice": {
"price": 6.2508,
"cost": 6.2508,
"currency": "USD",
"unit": "month"
},
"dateCreated": "2020-11-02T16:36:32Z",
"lastUpdated": "2021-06-21T21:00:01Z",
"hostName": "sa-apache-1",
"domainName": null,
"environmentPrefix": null,
"firewallEnabled": true,
"networkLevel": "container",
"autoScale": false,
"instanceContext": null,
"currentDeployId": null,
"locked": false,
"status": "running",
"statusMessage": null,
"errorMessage": null,
"statusDate": "2020-11-02T16:38:12Z",
"statusPercent": null,
"statusEta": null,
"userStatus": null,
"expireDays": null,
"renewDays": null,
"expireCount": 0,
"expireDate": null,
"expireWarningDate": null,
"expireWarningSent": false,
"shutdownDays": null,
"shutdownRenewDays": null,
"shutdownCount": 0,
"shutdownDate": null,
"shutdownWarningDate": null,
"shutdownWarningSent": false,
"removalDate": null,
"createdBy": {
"id": 1,
"username": "admin"
},
"owner": {
"id": 1,
"username": "admin"
},
"notes": null,
"stats": {
"usedStorage": 0,
"maxStorage": 10737418240,
"usedMemory": 233500000,
"maxMemory": 500212000,
"usedCpu": 0.0667445352,
"cpuUsage": 0.0667445352,
"cpuUsagePeak": 0.0667445352,
"cpuUsageAvg": 0.0667445352
},
"powerSchedule": null,
"isScalable": true,
"instanceThreshold": null,
"isBusy": false,
"apps": [
],
"currentLoadBalancerInstances": [
],
"currentLoadBalancerContainersIn": 0,
"currentLoadBalancerContainersOut": 0,
"lastDeploy": null,
"containerDetails": [
{
"id": 945,
"uuid": "c19f7209-df3a-443c-93a8-ccefacb3783c",
"name": "sa-apache-1_945",
"ip": "10.100.1.8",
"internalIp": "10.100.1.8",
"internalHostname": "container945",
"externalHostname": "sa-apache-1",
"externalDomain": "localdomain",
"externalFqdn": "sa-apache-1.localdomain",
"accountId": 1,
"instance": {
"id": 392,
"name": "sa-apache-1"
},
"containerType": {
"id": 31,
"code": "apache-amazon-2.4",
"category": "apache",
"name": "Apache 2.4"
},
"containerTypeSet": {
"id": 31,
"code": "apache-amazon-2.4-set",
"category": "apache"
},
"server": {
"id": 4002,
"uuid": "fbf4234d-cd25-47b5-bdd1-49a9132d2871",
"externalId": "i-033fbb2f1a9c2c225",
"internalId": null,
"externalUniqueId": null,
"name": "sa-apache-1",
"externalName": "sa-apache-1",
"hostname": "sa-apache-1",
"accountId": 1,
"account": {
"id": 1,
"name": "Morpheus Data"
},
"owner": {
"id": 1,
"username": "admin"
},
"zone": {
"id": 39,
"name": "amazon"
},
"plan": {
"id": 1,
"code": "amazon-t2.nano",
"name": "Amazon T2 Nano - 1 Core, 0.5GB Memory"
},
"computeServerType": {
"id": 45,
"code": "amazonVm",
"name": "Amazon Instance",
"managed": true,
"externalDelete": true
},
"visibility": "private",
"description": null,
"zoneId": 39,
"siteId": 1,
"resourcePoolId": 173,
"folderId": null,
"sshHost": null,
"sshPort": 22,
"externalIp": null,
"internalIp": "10.100.1.8",
"platform": "ubuntu",
"platformVersion": "14.04",
"dateCreated": "2020-11-02T16:36:32Z",
"lastUpdated": "2021-06-22T18:06:32Z",
"stats": {
"ts": "2021-06-22T18:06:28+0000",
"freeMemory": 266712000,
"usedMemory": 233500000,
"freeSwap": 0,
"usedSwap": 0,
"cpuIdleTime": 692815380,
"cpuSystemTime": 224850,
"cpuUserTime": 382640,
"cpuTotalTime": 693422870,
"cpuUsage": 0.06674528121948242,
"maxStorage": 10737418240,
"usedStorage": 1568661504,
"reservedStorage": 10423046144,
"netTxUsage": 27,
"netRxUsage": 23,
"networkBandwidth": 0
},
"status": "provisioned",
"statusMessage": null,
"errorMessage": null,
"statusDate": "2020-11-02T16:36:50Z",
"statusPercent": null,
"statusEta": null,
"powerState": "on",
"agentInstalled": true,
"lastAgentUpdate": "2021-06-22T18:06:32Z",
"agentVersion": "2.0.0",
"maxCores": 1,
"coresPerSocket": 1,
"maxMemory": 536870912,
"maxStorage": 10737418240,
"maxCpu": null,
"hourlyCost": 0.0086816667,
"hourlyPrice": 0.0086816667,
"sourceImage": {
"id": 22,
"code": "amazon.ec2.image.morpheus.apache.2.4",
"name": "ubuntu-14_04-apache-2_4-morph.0.1"
},
"serverOs": {
"id": 5,
"code": "ubuntu.14.04.64",
"name": "ubuntu 14 64-bit",
"description": null,
"vendor": "canonical",
"category": "ubuntu",
"osFamily": "debian",
"osVersion": "14.04",
"bitCount": 64,
"platform": "linux"
},
"volumes": [
{
"id": 177034,
"name": "root",
"controllerId": null,
"controllerMountPoint": null,
"resizeable": true,
"rootVolume": true,
"unitNumber": null,
"typeId": 5,
"configurableIOPS": false,
"datastoreId": null,
"maxStorage": 10737418240,
"displayOrder": 0,
"maxIOPS": null
}
],
"controllers": [
],
"interfaces": [
{
"id": 297842,
"refType": null,
"refId": null,
"name": "eth0",
"internalId": null,
"externalId": "eni-0689d61ea999db573",
"uniqueId": "morpheus-nic-392-945-0",
"publicIpAddress": null,
"publicIpv6Address": null,
"ipAddress": "10.100.1.8",
"ipv6Address": null,
"ipSubnet": null,
"ipv6Subnet": null,
"description": "",
"dhcp": true,
"active": true,
"poolAssigned": false,
"primaryInterface": true,
"network": {
"id": 365,
"name": "labs1"
},
"subnet": null,
"networkGroup": null,
"networkPosition": null,
"networkPool": null,
"networkDomain": null,
"type": {
"id": 1,
"code": "standard",
"name": "standard"
},
"ipMode": "",
"macAddress": "06:92:59:62:73:a3"
}
],
"labels": [
],
"tags": [
{
"id": 70536,
"name": "Morpheus Id",
"value": "945"
},
{
"id": 70535,
"name": "Morpheus Instance Id",
"value": "392"
},
{
"id": 70537,
"name": "Morpheus Labels",
"value": "foo,bar"
},
{
"id": 70534,
"name": "Morpheus Server Id",
"value": "4002"
},
{
"id": 70531,
"name": "abc",
"value": "123"
}
],
"enabled": true,
"tagCompliant": null
},
"cloud": {
"id": 39,
"name": "amazon"
},
"ports": [
{
"id": 192,
"index": 0,
"external": 80,
"internal": 80,
"displayName": "Http",
"primaryPort": false,
"export": true,
"visible": true,
"exportName": "HTTP",
"loadBalanceProtocol": null,
"loadBalance": true,
"protocol": "http",
"link": true,
"externalIp": null,
"internalIp": null
},
{
"id": 193,
"index": 1,
"external": 443,
"internal": 443,
"displayName": "Https",
"primaryPort": false,
"export": true,
"visible": true,
"exportName": "HTTPS",
"loadBalanceProtocol": null,
"loadBalance": true,
"protocol": "https",
"link": true,
"externalIp": null,
"internalIp": null
}
],
"plan": {
"id": 1,
"code": "amazon-t2.nano",
"name": "Amazon T2 Nano - 1 Core, 0.5GB Memory"
},
"configGroup": null,
"configId": null,
"configRole": null,
"dateCreated": "2020-11-02T16:36:32Z",
"lastUpdated": "2021-06-22T18:06:32Z",
"statsEnabled": true,
"status": "running",
"userStatus": "running",
"environmentPrefix": null,
"stats": {
"ts": "2021-06-22T18:06:28+0000",
"running": true,
"userCpuUsage": 0.0333722676,
"systemCpuUsage": 0.0333722676,
"usedMemory": 233500000,
"maxMemory": 500212000,
"cacheMemory": 190968000,
"maxStorage": null,
"usedStorage": 0,
"readIOPS": 0,
"writeIOPS": 0.2333333333,
"totalIOPS": 0.2333333333,
"iops": {
},
"netTxUsage": 27,
"netRxUsage": 23
},
"runtimeInfo": {
},
"containerVersion": null,
"repositoryImage": null,
"planCategory": null,
"hostname": "sa-apache-1",
"domainName": null,
"volumeCreated": false,
"containerCreated": true,
"maxStorage": 10737418240,
"maxMemory": 536870912,
"maxCores": 1,
"coresPerSocket": 1,
"maxCpu": 1,
"hourlyCost": 0.0086816667,
"hourlyPrice": 0.0086816667
}
]
}
}
This endpoint retrieves a specific instance.
HTTP Request
GET $serverUrl/api/instances/:id
URL Parameters
| Parameter | Description |
|---|---|
| id | ID of the instance |
Query Parameters
| Parameter | Default | Description |
|---|---|---|
| details | true | More details about the instance are returned by default, ie. containerDetails. Available in api version 5.2.8/5.3.2. |
Get Env Variables
curl "$serverUrl/api/instances/1216/envs" \
-H "Authorization: BEARER $accessToken"
The above command returns JSON structured like this:
{
"envs": [
{
"export": false,
"masked": false,
"name": "DATABASE_NAME",
"value": "spud_marketing"
}
],
"readOnlyEnvs": {
"TOMCAT_HOST": {
"export": true,
"masked": false,
"name": "TOMCAT_HOST",
"value": "container1414"
},
"TOMCAT_HOST_2": {
"export": true,
"masked": false,
"name": "TOMCAT_HOST_2",
"value": "container1759"
},
"TOMCAT_IP": {
"export": true,
"masked": false,
"name": "TOMCAT_IP",
"value": "192.168.163.232"
},
"TOMCAT_IP_2": {
"export": true,
"masked": false,
"name": "TOMCAT_IP_2",
"value": "192.168.163.233"
},
"TOMCAT_PORT": {
"export": true,
"masked": false,
"name": "TOMCAT_PORT",
"value": 10017
},
"TOMCAT_PORT_2": {
"export": true,
"masked": false,
"name": "TOMCAT_PORT_2",
"value": 10017
},
"TOMCAT_PORT_8080_TCP": {
"export": true,
"masked": false,
"name": "TOMCAT_PORT_8080_TCP",
"value": "tcp://192.168.163.232:10017"
},
"TOMCAT_PORT_8080_TCP_2": {
"export": true,
"masked": false,
"name": "TOMCAT_PORT_8080_TCP_2",
"value": "tcp://192.168.163.233:10017"
},
"TOMCAT_PORT_8080_TCP_ADDR": {
"export": true,
"masked": false,
"name": "TOMCAT_PORT_8080_TCP_ADDR",
"value": "192.168.163.232"
},
"TOMCAT_PORT_8080_TCP_ADDR_2": {
"export": true,
"masked": false,
"name": "TOMCAT_PORT_8080_TCP_ADDR_2",
"value": "192.168.163.233"
},
"TOMCAT_PORT_8080_TCP_PORT": {
"export": true,
"masked": false,
"name": "TOMCAT_PORT_8080_TCP_PORT",
"value": 10017
},
"TOMCAT_PORT_8080_TCP_PORT_2": {
"export": true,
"masked": false,
"name": "TOMCAT_PORT_8080_TCP_PORT_2",
"value": 10017
},
"TOMCAT_PORT_8080_TCP_PROTO": {
"export": true,
"masked": false,
"name": "TOMCAT_PORT_8080_TCP_PROTO",
"value": "tcp"
},
"TOMCAT_PORT_8080_TCP_PROTO_2": {
"export": true,
"masked": false,
"name": "TOMCAT_PORT_8080_TCP_PROTO_2",
"value": "tcp"
}
},
"importedEnvs": {
"MYSQL_HOST": {
"export": true,
"masked": false,
"name": "MYSQL_HOST",
"value": "container1413"
},
"MYSQL_HOST_2": {
"export": true,
"masked": false,
"name": "MYSQL_HOST_2",
"value": "container1756"
},
"MYSQL_IP": {
"export": true,
"masked": false,
"name": "MYSQL_IP",
"value": "192.168.163.232"
},
"MYSQL_IP_2": {
"export": true,
"masked": false,
"name": "MYSQL_IP_2",
"value": "192.168.163.233"
},
"MYSQL_MASTER": {
"export": true,
"masked": false,
"name": "MYSQL_HOST",
"value": "container1413"
},
"MYSQL_PASSWORD": {
"export": true,
"masked": true,
"name": "MYSQL_PASSWORD",
"value": "************"
},
"MYSQL_PASSWORD_2": {
"export": true,
"masked": true,
"name": "MYSQL_PASSWORD",
"value": "************"
},
"MYSQL_PORT": {
"export": true,
"masked": false,
"name": "MYSQL_PORT",
"value": 10016
},
"MYSQL_PORT_2": {
"export": true,
"masked": false,
"name": "MYSQL_PORT_2",
"value": 10016
},
"MYSQL_PORT_3306_TCP": {
"export": true,
"masked": false,
"name": "MYSQL_PORT_3306_TCP",
"value": "tcp://192.168.163.232:10016"
},
"MYSQL_PORT_3306_TCP_2": {
"export": true,
"masked": false,
"name": "MYSQL_PORT_3306_TCP_2",
"value": "tcp://192.168.163.233:10016"
},
"MYSQL_PORT_3306_TCP_ADDR": {
"export": true,
"masked": false,
"name": "MYSQL_PORT_3306_TCP_ADDR",
"value": "192.168.163.232"
},
"MYSQL_PORT_3306_TCP_ADDR_2": {
"export": true,
"masked": false,
"name": "MYSQL_PORT_3306_TCP_ADDR_2",
"value": "192.168.163.233"
},
"MYSQL_PORT_3306_TCP_PORT": {
"export": true,
"masked": false,
"name": "MYSQL_PORT_3306_TCP_PORT",
"value": 10016
},
"MYSQL_PORT_3306_TCP_PORT_2": {
"export": true,
"masked": false,
"name": "MYSQL_PORT_3306_TCP_PORT_2",
"value": 10016
},
"MYSQL_PORT_3306_TCP_PROTO": {
"export": true,
"masked": false,
"name": "MYSQL_PORT_3306_TCP_PROTO",
"value": "tcp"
},
"MYSQL_PORT_3306_TCP_PROTO_2": {
"export": true,
"masked": false,
"name": "MYSQL_PORT_3306_TCP_PROTO_2",
"value": "tcp"
},
"MYSQL_USERNAME": "root",
"MYSQL_USERNAME_2": "root"
}
}
This gets all the environment variables associated with the instance.
HTTP Request
GET $serverUrl/api/instances/:id/envs
URL Parameters
| Parameter | Description |
|---|---|
| id | ID of the instance |
Get Instance History
curl "$serverUrl/api/instances/238/history" \
-H "Authorization: BEARER $accessToken"
The above command returns JSON structured like this:
{
"processes": [
{
"id": 250,
"accountId": 1,
"uniqueId": "cebc47ec-cb2f-417a-886e-dd60cf81db26",
"processType": {
"code": "provision",
"name": "provision"
},
"description": null,
"subType": null,
"subId": null,
"zoneId": 34,
"integrationId": null,
"instanceId": 238,
"containerId": 240,
"serverId": 601,
"containerName": "apachetest",
"displayName": "apachetest",
"timerCategory": "vmware",
"timerSubCategory": "28",
"status": "failed",
"reason": null,
"percent": 100.0,
"statusEta": 348246,
"message": null,
"output": null,
"error": null,
"startDate": "2018-09-28T19:10:56+0000",
"endDate": "2018-09-28T20:21:49+0000",
"duration": 4253127,
"dateCreated": "2018-09-28T19:10:56+0000",
"lastUpdated": "2018-09-28T20:21:49+0000",
"createdBy": {
"username": "admin",
"displayName": "Admin"
},
"updatedBy": {
"username": "admin",
"displayName": "Admin"
},
"events": [
]
}
],
"meta": {
"size": 1,
"total": 1,
"offset": 0,
"max": 25
}
}
This endpoint retrieves the process history for a specific instance.
Alternatively, the Process History endpoint can be used to get the same information.
HTTP Request
GET $serverUrl/api/instances/:id/history
URL Parameters
| Parameter | Description |
|---|---|
| id | ID of the instance |
Query Parameters
| Parameter | Default | Description |
|---|---|---|
| phrase | If specified will return a partial match on displayName, message or output | |
| containerId | Filter by container id(s) | |
| serverId | Filter by server id(s) | |
| zoneId | Filter by zone id(s) |
Get Container Details
curl "$serverUrl/api/instances/1216/containers" \
-H "Authorization: BEARER $accessToken"
The above command returns JSON structured like this:
{
"containers": [
{
"id": 292,
"accountId": 1,
"instance": {
"id": 294,
"name": "nginxtest"
},
"containerType": {
"id": 187,
"code": "nginx-vmware-1.9",
"category": "nginx",
"name": "NGINX 1.9"
},
"containerTypeSet": {
"id": 193,
"code": "nginx-vmware-1.9-set",
"category": "nginx"
},
"server": {
"id": 653,
"name": "nginxtest"
},
"cloud": {
"id": 34,
"name": "myvmware"
},
"name": "nginxtest_292",
"ip": "10.30.20.50",
"internalIp": "10.30.20.50",
"internalHostname": "container292",
"externalHostname": "nginxtest",
"externalDomain": "localdomain",
"externalFqdn": "nginxtest.localdomain",
"ports": [
{
"index": 0,
"external": 80,
"internal": 80,
"primaryPort": true,
"displayName": "Http",
"export": true,
"visible": true,
"loadBalance": true,
"link": true,
"exportName": "HTTP",
"protocol": "http",
"code": "nginx.80"
},
{
"index": 1,
"external": 443,
"internal": 443,
"primaryPort": false,
"displayName": "Https",
"export": true,
"visible": true,
"loadBalance": true,
"link": true,
"exportName": "HTTPS",
"protocol": "https",
"code": "nginx.443"
}
],
"plan": {
"id": 76,
"code": "vm-1024",
"name": "1 CPU, 1GB Memory"
},
"dateCreated": "2019-02-20T18:29:05+0000",
"lastUpdated": "2019-02-27T21:07:35+0000",
"statsEnabled": true,
"status": "running",
"userStatus": "running",
"environmentPrefix": null,
"stats": {
"ts": "2019-02-27T21:07:31+0000",
"running": true,
"userCpuUsage": 0.1504010695,
"systemCpuUsage": 0.1838235294,
"usedMemory": 317256000,
"maxMemory": 1017032000,
"cacheMemory": 404236000,
"maxStorage": 10499452928,
"usedStorage": 3700285440,
"readIOPS": 0,
"writeIOPS": 0.35,
"totalIOPS": 0.35,
"iops": {
},
"netTxUsage": 114,
"netRxUsage": 2198
},
"runtimeInfo": {
},
"containerVersion": null,
"repositoryImage": null,
"planCategory": null,
"hostname": "nginxtest",
"domainName": null,
"volumeCreated": true,
"containerCreated": false,
"maxStorage": 10737418240,
"maxMemory": 1073741824,
"maxCores": 1,
"coresPerSocket": 1,
"maxCpu": 1,
"availableActions": [
{
"code": "nginx-1.9-remove-node",
"name": "Remove Nginx Node"
}
]
}
]
}
This can be valuable for evaluating the details of the compute server(s) running on an instance
HTTP Request
GET $serverUrl/api/instances/:id/containers
URL Parameters
| Parameter | Description |
|---|---|
| id | ID of the instance |
Get All Instance Types for Provisioning
curl "$serverUrl/api/instance-types"
-H "Authorization: BEARER $accessToken"
The above command returns JSON structured like this
{
"instanceTypes": [
{
"id": 12,
"name": "ActiveMQ",
"code": "activemq",
"category": "messaging",
"active": true,
"versions": [
"5.11"
],
"instanceTypeLayouts": [
{
"id": 14,
"code": "activemq-5.11",
"name": "Single Process",
"description": "This will provision a single process with no redundancy",
"provisionType": { /* see provision types */ },
"optionTypes": { /** see option types **/}
}
]
},
{
"id": 13,
"name": "Cassandra",
"code": "cassandra",
"category": "nosql",
"active": true,
"versions": [
"2.1"
],
"instanceTypeLayouts": [
{
"id": 15,
"code": "cassandra-2.1-single",
"name": "Single Process",
"description": "This will provision a single process with no redundancy",
"provisionType": { /* see provision types */ },
"optionTypes": { /** see option types **/ }
}
]
},
{
"id": 10,
"name": "Confluence",
"code": "confluence",
"category": "utils",
"active": true,
"versions": [
"5.7"
],
"instanceTypeLayouts": [
{
"id": 12,
"code": "confluence-5.7",
"name": "Single Process",
"description": "This will provision a single process with no redundancy",
"provisionType": { /* see provision types */ },
"optionTypes": { /** see option types **/ }
}
]
},
{
"id": 5,
"name": "Elastic Search",
"code": "elasticsearch",
"category": "nosql",
"active": true,
"versions": [
"1.5"
],
"instanceTypeLayouts": [
{
"id": 3,
"code": "elasticsearch-1.5-single",
"name": "Single Process",
"description": "This will provision a single process with no redundancy",
"provisionType": { /* see provision types */ },
"optionTypes": { /** see option types **/ }
},
{
"id": 4,
"code": "elasticsearch-1.5-cluster",
"name": "Cluster",
"description": "This will provision two nodes, in multi master cluster",
"provisionType": { /* see provision types */ },
"optionTypes": { /** see option types **/ }
}
]
},
{
"id": 7,
"name": "Jenkins",
"code": "jenkins",
"category": "utils",
"active": true,
"versions": [
"1.596"
],
"instanceTypeLayouts": [
{
"id": 8,
"code": "jenkins-1.596",
"name": "Single Process",
"description": "This will provision a single process with no redundancy",
"provisionType": { /* see provision types */ },
"optionTypes": { /** see option types **/ }
}
]
},
{
"id": 2,
"name": "Memcached",
"code": "memcached",
"category": "cache",
"active": true,
"versions": [
"1.4"
],
"instanceTypeLayouts": [
{
"id": 11,
"code": "memcached-1.4-single",
"name": "Single Process",
"description": "This will provision a single process with no redundancy",
"provisionType": { /* see provision types */ },
"optionTypes": { /** see option types **/ }
}
]
},
{
"id": 4,
"name": "Mongo",
"code": "mongo",
"category": "nosql",
"active": true,
"versions": [
"3.0"
],
"instanceTypeLayouts": [
{
"id": 16,
"code": "mongo-3.0-rs",
"name": "ReplicaSet",
"description": "This will provision a 3 node replicaSet",
"provisionType": { /* see provision types */ },
"optionTypes": { /** see option types **/ }
},
{
"id": 6,
"code": "mongo-3.0-single",
"name": "Single Process",
"description": "This will provision a single process with no redundancy",
"provisionType": { /* see provision types */ },
"optionTypes": { /** see option types **/ }
}
]
},
{
"id": 3,
"name": "MySQL",
"code": "mysql",
"category": "sql",
"active": true,
"versions": [
"5.6"
],
"instanceTypeLayouts": [
{
"id": 5,
"code": "mysql-5.6-single",
"name": "Single Process",
"description": "This will provision a single process with no redundancy",
"provisionType": { /* see provision types */ },
"optionTypes": { /** see option types **/ }
}
]
},
{
"id": 8,
"name": "Nexus",
"code": "nexus",
"category": "utils",
"active": true,
"versions": [
"2.11"
],
"instanceTypeLayouts": [
{
"id": 9,
"code": "nexus-2.11",
"name": "Single Process",
"description": "This will provision a single process with no redundancy",
"provisionType": { /* see provision types */ },
"optionTypes": { /** see option types **/ }
}
]
},
{
"id": 14,
"name": "Nginx",
"code": "nginx",
"category": "web",
"active": true,
"versions": [
"1.9"
],
"instanceTypeLayouts": [
]
},
{
"id": 11,
"name": "Postgres",
"code": "postgres",
"category": "sql",
"active": true,
"versions": [
"9.4"
],
"instanceTypeLayouts": [
{
"id": 13,
"code": "postgres-9.4-single",
"name": "Single Process",
"description": "This will provision a single process with no redundancy",
"provisionType": { /* see provision types */ },
"optionTypes": { /** see option types **/ }
}
]
},
{
"id": 9,
"name": "RabbitMQ",
"code": "rabbitmq",
"category": "utils",
"active": true,
"versions": [
"3.5"
],
"instanceTypeLayouts": [
{
"id": 10,
"code": "rabbitmq-3.5",
"name": "Single Process",
"description": "This will provision a single process with no redundancy",
"provisionType": { /* see provision types */ },
"optionTypes": { /** see option types **/ }
}
]
},
{
"id": 1,
"name": "Redis",
"code": "redis",
"category": "cache",
"active": true,
"versions": [
"3.0"
],
"instanceTypeLayouts": [
{
"id": 1,
"code": "redis-3.0-single",
"name": "Single Process",
"description": "This will provision a single process with no redundancy",
"provisionType": { /* see provision types */ },
"optionTypes": { /** see option types **/ }
},
{
"id": 2,
"code": "redis-3.0-master-slave",
"name": "Master\/Slave",
"description": "This will provision 2 containers, one master and 1 slave.",
"provisionType": { /* see provision types */ },
"optionTypes": { /** see option types **/ }
}
]
},
{
"id": 6,
"name": "Tomcat",
"code": "tomcat",
"category": "web",
"active": true,
"versions": [
"7.0.62"
],
"instanceTypeLayouts": [
{
"id": 7,
"code": "tomcat-7.0.62-single",
"name": "Single Process",
"description": "This will provision a single process with no redundancy",
"provisionType": { /* see provision types */ },
"optionTypes": { /** see option types **/ }
}
]
}
]
}
Fetch the list of available instance types. These can vary in range from database containers, to web containers, to custom containers.
HTTP Request
GET $serverUrl/api/instance-types
Get Specific Instance Type for Provisioning
curl "$serverUrl/api/instance-types/12"
-H "Authorization: BEARER $accessToken"
The above command returns JSON structured like this
{
"success": true,
"instanceType": {
"id": 12,
"name": "ActiveMQ",
"code": "activemq",
"category": "messaging",
"active": true,
"versions": [
"5.11"
],
"instanceTypeLayouts": [
{
"id": 14,
"code": "activemq-5.11",
"name": "Single Process",
"description": "This will provision a single process with no redundancy",
"provisionType": { /* see provision types */ },
"optionTypes": { /** see option types **/ }
}
]
}
}
Fetch an instance type by ID.
HTTP Request
GET $serverUrl/api/instance-types/:id
URL Parameters
| Parameter | Description |
|---|---|
| id | ID of the instance type |
Get Available Service Plans for an Instance
curl -XGET "$serverUrl/api/instances/service-plans?zoneId=1&layoutId=75" \
-H "Authorization: BEARER $accessToken"
The above command returns JSON structure like this:
{
"plans": [
{
"id": 75,
"name": "1 CPU, 512MB Memory",
"value": 75,
"code": "vm-512",
"maxStorage": 10737418240,
"maxMemory": 536870912,
"maxCpu": 1,
"maxCores": 1,
"customCpu": false,
"customMaxMemory": false,
"customMaxStorage": true,
"customMaxDataStorage": true,
"customCoresPerSocket": false,
"coresPerSocket": 1,
"storageTypes": [
{
"id": 1,
"editable": false,
"optionTypes": [
],
"displayOrder": 1,
"code": "standard",
"volumeType": "disk",
"minStorage": null,
"deletable": false,
"defaultType": true,
"createDatastore": null,
"resizable": false,
"storageType": null,
"allowSearch": true,
"volumeOptionSource": null,
"displayName": "Disk",
"minIOPS": null,
"maxIOPS": null,
"hasDatastore": true,
"customSize": true,
"autoDelete": true,
"name": "Standard",
"configurableIOPS": false,
"customLabel": true,
"enabled": true,
"description": "Standard",
"volumeCategory": "disk",
"externalId": null,
"maxStorage": null
}
],
"rootStorageTypes": [
{
"id": 1,
"editable": false,
"optionTypes": [
],
"displayOrder": 1,
"code": "standard",
"volumeType": "disk",
"minStorage": null,
"deletable": false,
"defaultType": true,
"createDatastore": null,
"resizable": false,
"storageType": null,
"allowSearch": true,
"volumeOptionSource": null,
"displayName": "Disk",
"minIOPS": null,
"maxIOPS": null,
"hasDatastore": true,
"customSize": true,
"autoDelete": true,
"name": "Standard",
"configurableIOPS": false,
"customLabel": true,
"enabled": true,
"description": "Standard",
"volumeCategory": "disk",
"externalId": null,
"maxStorage": null
}
],
"addVolumes": true,
"customizeVolume": true,
"rootDiskCustomizable": true,
"noDisks": false,
"hasDatastore": true,
"minDisk": 0,
"maxDisk": null,
"lvmSupported": true,
"datastores": {
"cluster": [
{
"id": 54,
"name": "demo-qnap - 4.3TB Free"
}
],
"store": [
{
"id": 50,
"name": "datastore1 - 463.4GB Free"
}
]
},
"supportsAutoDatastore": true,
"autoOptions": [
{
"id": "autoCluster",
"name": "Auto - Cluster"
},
{
"id": "auto",
"name": "Auto - Datastore"
}
],
"cpuOptions": [
],
"coreOptions": [
],
"memoryOptions": [
],
"rootCustomSizeOptions": {
},
"customSizeOptions": {
},
"customCores": false,
"maxDisks": null,
"memorySizeType": "MB"
}
]
}
This endpoint retrieves all the Service Plans available for the specified cloud and instance layout. The response includes details about the plans and their configuration options. It may be used to get the list of available plans when creating a new instance or resizing an existing instance.
HTTP Request
GET $serverUrl/api/instances/service-plans?zoneId=:zoneId&layoutId=:layoutId&siteId=:siteId
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| zoneId | Y | The ID of the Cloud |
| layoutId | Y | The ID of the Instance Layout |
| siteId | N | The ID of the Group |
Create an Instance
curl -X POST "$serverUrl/api/instances" \
-H "Authorization: BEARER $accessToken" \
-H "Content-Type: application/json" \
-d '{
"zoneId": 6,
"instance": {
"name": "api-testing2",
"site": {
"id": 3
},
"instanceType": {
"code": "Ubuntu"
},
"layout": {
"id": 105
},
"plan": {
"id": 75
}
},
"volumes": [
{
"id": -1,
"rootVolume": true,
"name": "root",
"size": 10,
"sizeId": null,
"storageType": 1,
"datastoreId": "autoCluster"
},
{
"id": -1,
"rootVolume": false,
"name": "data",
"size": 5,
"sizeId": null,
"storageType": 1,
"datastoreId": "auto"
}
],
"servicePlanOptions": {
"maxCores": 1,
"coresPerSocket": 1,
"maxMemory": 536870912
},
"networkInterfaces": [
{
"network": {
"id": 5
},
"networkInterfaceTypeId": 4
}
],
"config": {
"publicKeyId": 14,
"vmwareResourcePoolId": "resgroup-56",
"hostId": null,
"vmwareUsr": "apiuser",
"vmwarePwd": "password",
"vmwareDomainName": null,
"vmwareCustomSpec": null
},
"evars": [
{"name": "MY_APP_VAR1", "value": "VALUE1"},
{"name": "MY_APP_VAR2", "value": "VALUE2"}
],
"labels": [
"foo", "bar"
],
"tags": [
{"name": "hello", "value": "world"},
{"name": "flash", "value": "bang"}
]
}'
The above command returns a similar JSON structure when submitting a GET request for a single instance
HTTP Request
POST $serverUrl/api/instances
JSON Parameters
| Parameter | Required | Default | Description |
|---|---|---|---|
| instance | Y | n/a | Key for name, site, instanceType layout, and plan |
| instance.name | Y | Name of the instance to be created | |
| instance.site.id | Y | The Group ID to provision the instance into | |
| instance.instanceType.code | Y | The type of instance by code we want to fetch | |
| instance.layout.id | Y | The layout id for the instance type that you want to provision. i.e. single process or cluster | |
| instance.plan.id | Y | The id for the memory and storage option pre-configured within Morpheus. See Available Service Plans | |
| zoneId | Y | The Cloud ID to provision the instance onto | |
| evars | N | [] | Environment Variables, an array of objects that have name and value. |
| copies | N | 1 | Number of copies to provision |
| layoutSize | N | 1 | Apply a multiply factor of containers/vms within the instance |
| servicePlanOptions | N | Map of custom options depending on selected service plan. | |
| servicePlanOptions.maxCores | N | Core Count | |
| servicePlanOptions.coresPerSocket | N | Cores Per Socket | |
| servicePlanOptions.maxMemory | N | Memory in bytes For backwards compatability, values less than 1048576 are treated as being in MB and will be converted to bytes | |
| securityGroups | N | Key for security group configuration. It should be passed as an array of objects containing the id of the security group to assign the instance to | |
| volumes | N | Key for volume configuration, see Volumes | |
| networkInterfaces | N | Key for network configuration, see Network Interfaces | |
| config | Y | Key for specific type configuration, see Config | |
| labels | N | Array of strings (keywords) | |
| tags | N | Metadata tags, Array of objects having a name and value. | |
| metadata | N | Alias for tags |
|
| ports | N | Array of port objects, see Exposed Ports | |
| taskSetId | N | The Workflow ID to execute. | |
| taskSetName | N | The Workflow Name to execute. |
Volumes
The (optional) volumes parameter is for LV configuration, can create additional LVs at provision
It should be passed as an array of Objects with the following attributes:
| Parameter | Required | Default | Description |
|---|---|---|---|
| id | N | -1 | The id for the LV configuration being created |
| rootVolume | N | true | If set to false then a non-root LV will be created |
| name | Y | root | Name/type of the LV being created |
| size | N | [from service plan] | Size of the LV to be created in GBs |
| sizeId | N | Can be used to select pre-existing LV choices from Morpheus | |
| storageType | N | Identifier for LV type | |
| datastoreId | Y | The ID of the specific datastore. Auto selection can be specified as auto or autoCluster (for clusters). |
Network Interfaces
The networkInterfaces parameter is for network configuration.
The Options API /api/options/zoneNetworkOptions?zoneId=5&provisionTypeId=10 can be used to see which options are available.
It should be passed as an array of Objects with the following attributes:
| Parameter | Required | Default | Description |
|---|---|---|---|
| network.id | Y | n/a | id of the network to be used. A network group can be specified instead by prefixing its ID with networkGroup-. |
| networkInterfaceTypeId | Y | n/a | The id of type of the network interface. |
| ipAddress | Y | n/a | The ip address. Not applicable when using DHCP or IP Pools. |
| id | N | n/a | The interface id. Applicable when resizing and you want to identify an interface to update that already exists. |
Exposed Ports
The ports parameter is for port configuration.
The layout may have default ports, which are defined in node types, that are always configured. This parameter will be for additional custom ports to be opened.
It should be passed as an array of Objects with the following attributes:
| Parameter | Required | Default | Description |
|---|---|---|---|
| port | Y | n/a | port number. eg. 8080 |
| name | N | n/a | A name for the port eg. web |
| lb | N | The load balancer protocol. HTTP, HTTPS, or TCP. Default is none. |
Config
The config parameter is for configuration options that are specific to each Provision Type.
The Provision Types api can be used to see which options are available.
JSON Config Parameters for VMware
| Parameter | Required | Default | Description |
|---|---|---|---|
| publicKeyId | N | ID of a public key to add to the instance | |
| resourcePoolId | Y | External ID of the resource group to use for instance | |
| hostId | N | Specific host to deploy to if so desired | |
| vmwareUsr | N | Additional user to provision to instance | |
| vmwarePwd | N | Password for additional user | |
| vmwareDomainName | N | Domain name to be given to instance | |
| vmwareCustomSpec | N | Customization spec ID |
JSON Config Parameters for Docker
| Parameter | Required | Default | Description |
|---|---|---|---|
| provisionServerId | N | Specific host to deploy to if so desired | |
| resourcePoolId | Y | External ID of the resource group to use for instance |
JSON Config Parameters for Kubernetes
| Parameter | Required | Default | Description |
|---|---|---|---|
| resourcePoolId | Y | ID of the resource group (kubernetes cluster) to use for instance |
Metadata
This is specific to AWS Metadata tags. Name-Values pairs can be anything you like and are added to the instance JSON as an array of n-v pairs per the example to the right:
-d '{
"zoneId": 6,
"instance": {
...
}
...
"tags": [
{
"name": "Tag Name",
"value": "Sample Value"
},
{
"name": "BusinessUnit",
"value": "QualityAssurance"
}
]
...
}
There can be additional properties to apply to the instance. For example mysql provisioning requires a set of initial credentials. You can get a list of what these input options are by fetching the instance-types list via the instance-types api and getting available layouts as well as the provision type option types associated with the layout. Currently these input options are available from the option-types map. These however, can be overridden in the event a config options map exists on the layout object within. NOTE: See the API Document on OptionTypes for figuring out how to build property maps from them.
Updating an Instance
curl -X PUT "$serverUrl/api/instances/1" \
-H "Authorization: BEARER $accessToken" \
-H "Content-Type: application/json" \
-d '{
"instance": {
"description": "my new redis",
"addTags": [
{"name": "hello", "value": "world"},
{"name": "flash", "value": "bang"}
],
"removeTags": [
{"name": "oldTag"}
]
},
"config": {
"customOptions": {
"dbfoldername": "data"
}
}
}'
The above command returns a similar JSON structure when submitting a GET request for a single instance
HTTP Request
PUT $serverUrl/api/instances/:id
URL Parameters
| Parameter | Description |
|---|---|
| id | ID of the instance |
JSON Instance Parameters
| Parameter | Default | Description |
|---|---|---|
| name | Unique name scoped to your account for the instance | |
| description | Optional description field | |
| instanceContext | Environment | |
| labels | Array of strings (keywords) | |
| tags | Metadata tags, Array of objects having a name and value, this adds or updates the specified tags and removes any tags not specified. | |
| addTags | Add or update value of Metadata tags, Array of objects having a name and value | |
| removeTags | Remove Metadata tags, Array of objects having a name and an optional value. If value is passed, it must match to be removed. | |
| powerScheduleType | Power Schedule ID | |
| site.id | Group ID | |
| ownerId | User ID, can be used to change instance owner. | |
| config.customOptions | Custom Option Type settings object containing name value pairs to be updated. |
Stop an Instance
curl -X PUT "$serverUrl/api/instances/1/stop" \
-H "Authorization: BEARER $accessToken"
The above command returns JSON structure like this:
{
"success": true
}
This will stop all containers running within an instance.
HTTP Request
PUT $serverUrl/api/instances/:id/stop
URL Parameters
| Parameter | Description |
|---|---|
| id | ID of the instance |
Start an Instance
curl -X PUT "$serverUrl/api/instances/1/start" \
-H "Authorization: BEARER $accessToken"
The above command returns JSON structure like this:
{
"success": true
}
This will start all containers running within an instance.
HTTP Request
PUT $serverUrl/api/instances/:id/start
URL Parameters
| Parameter | Description |
|---|---|
| id | ID of the instance |
Restart an Instance
curl -X PUT "$serverUrl/api/instances/1/restart" \
-H "Authorization: BEARER $accessToken"
The above command returns JSON structure like this:
{
"success": true
}
This will restart all containers running within an instance. This includes rebuilding the environment variables and applying settings to the docker containers.
HTTP Request
PUT $serverUrl/api/instances/:id/restart
URL Parameters
| Parameter | Description |
|---|---|
| id | ID of the instance |
Suspend an Instance
curl -X PUT "$serverUrl/api/instances/1/suspend" \
-H "Authorization: BEARER $accessToken"
The above command returns JSON structure like this:
{
"success": true
}
This will suspend all containers in the instance.
HTTP Request
PUT $serverUrl/api/instances/:id/suspend
URL Parameters
| Parameter | Description |
|---|---|
| id | ID of the instance |
Eject an Instance
curl -X PUT "$serverUrl/api/instances/1/eject" \
-H "Authorization: BEARER $accessToken"
The above command returns JSON structure like this:
{
"success": true
}
This will eject any ISO media on all containers in the instance.
HTTP Request
PUT $serverUrl/api/instances/:id/eject
URL Parameters
| Parameter | Description |
|---|---|
| id | ID of the instance |
Resize an Instance
curl -X PUT "$serverUrl/api/instances/1/resize" \
-H "Authorization: BEARER $accessToken" \
-H "Content-Type: application/json" \
-d '{
"instance": {
"id": 1,
"plan": {
"id": 15
}
},
"volumes": [
{
"id": "-1",
"rootVolume": true,
"name": "root",
"size": 20,
"sizeId": null,
"storageType": null,
"datastoreId": null
}
],
"deleteOriginalVolumes": true,
"servicePlanOptions": {
"maxCores": 1,
"coresPerSocket": 1,
"maxMemory": 536870912
},
"networkInterfaces": [
{
"id": 534,
"name": "eth0",
"network": {
"id": "network-20"
}
},
{
"name": "eth1",
"network": {
"id": "network-20"
}
}
]
}'
The above command returns JSON structure like this:
{
"success": true
}
It is possible to resize containers within an instance by increasing their memory plan or storage limit. This is done by assigning a new service plan to the container. This endpoint also allows for NIC reconfiguration by passing a new array of networkInterfaces.
HTTP Request
PUT $serverUrl/api/instances/:id/resize
URL Parameters
| Parameter | Description |
|---|---|
| id | ID of the instance |
JSON Parameters
| Parameter | Required | Default | Description |
|---|---|---|---|
| instance.plan.id | N | null | The map containing the id of the service plan you wish to apply to the containers in this instance |
| servicePlanOptions | N | Map of custom options depending on selected service plan. | |
| servicePlanOptions.maxCores | N | Core Count | |
| servicePlanOptions.coresPerSocket | N | Cores Per Socket | |
| servicePlanOptions.maxMemory | N | Memory in bytes For backwards compatability, values less than 1048576 are treated as being in MB and will be converted to bytes | |
| volumes | no | defaults to plan config | Can be used to grow just the logical volume of the instance instead of choosing a plan, see Volumes. |
| deleteOriginalVolumes | no | false | Delete the original volumes after resizing. (Amazon only) |
| networkInterfaces | N | Key for network configuration, see Network Interfaces. Include id to update an existing interface. The existing interfaces and their id can be retrieved with the hosts API. |
Run Workflow on an Instance
curl -X PUT "$serverUrl/api/instances/1/workflow?workflowId=99" \
-H "Authorization: BEARER $accessToken" \
-d '{ "taskSet": {
"customOptions": {"foo":"bar"}
}}'
The above command returns JSON structure like this:
{
"success": true
}
This will run a provisioning workflow on all containers in an instance.
For operational workflows, see Execute a Workflow.
HTTP Request
PUT $serverUrl/api/instances/:id/workflow
URL Parameters
| Parameter | Description |
|---|---|
| id | ID of the instance |
Query Parameters
| Parameter | Description |
|---|---|
| workflowId | ID of the workflow to execute |
| workflowName | Name of the workflow to execute |
JSON Parameters
| Parameter | Default | Description |
|---|---|---|
| taskSet | Object containing workflow configuration parameters | |
| taskSet.customOptions | Object containing any custom option type configuration parameters |
Clone an Instance
curl -X PUT "$serverUrl/api/instances/1/clone" \
-H "Authorization: BEARER $accessToken" \
-H "Content-Type: application/json" \
-d '{ "name": "New Name",
"group": {
"id": 1
}}'
The above command returns JSON structure like this:
{
"success": true
}
One can easily clone an instance and all containers within that instance. The containers are backed up via the backup services and used as a snapshot to produce a clone of the instance. It is possible to clone this app instance into an entirely different availability zone.
HTTP Request
PUT $serverUrl/api/instances/:id/clone
URL Parameters
| Parameter | Description |
|---|---|
| id | ID of the instance |
JSON Parameters
| Parameter | Default | Description |
|---|---|---|
| group | null | the map containing the id of the server group you would like to clone into. |
| group | null | the map containing the id of the server group you would like to clone into. |
| name | null | A name for the new cloned instance. If none is specified the existing name will be duplicated with the 'clone' suffix added. |
This endpoint also supports all of the same parameters as Create and Instance, so you can override any configuration options when provisioning the clone.
Backup an Instance
curl -X PUT "$serverUrl/api/instances/1773/backup" \
-H "Authorization: BEARER $accessToken"
The above command returns JSON structure that looks like this:
{
"success": true
}
HTTP Request
PUT $serverUrl/api/instances/:id/backup
URL Parameters
| Parameter | Description |
|---|---|
| id | ID of the instance |
Get list of backups for an Instance
curl "$serverUrl/api/instances/1773/backups" \
-H "Authorization: BEARER $accessToken"
The above command returns JSON structure that looks like this:
{
"instance": {
"id": 1773
},
"backups": [
]
}
HTTP Request
GET $serverUrl/api/instances/:id/backups
URL Parameters
| Parameter | Description |
|---|---|
| id | ID of the instance |
Get list of snapshots for an Instance
curl "$serverUrl/api/instances/1773/snapshots" \
-H "Authorization: BEARER $accessToken"
The above command returns JSON structure that looks like this:
{
"snapshots": [
]
}
HTTP Request
GET $serverUrl/api/instances/:id/snapshots
URL Parameters
| Parameter | Description |
|---|---|
| id | ID of the instance |
Get a Specific Snapshot
curl "$serverUrl/api/snapshots/1216" \
-H "Authorization: BEARER $accessToken"
The above command returns JSON structured like this:
{
"snapshot": {
"id": 59,
"name": "auto-apache-114-2022-01-14T12:57:17.981Z",
"description": null,
"externalId": "snapshot-56466",
"status": "complete",
"state": null,
"snapshotType": "vm",
"snapshotCreated": "2022-01-14T12:57:38Z",
"zone": {
"id": 2,
"name": "ld-vmware"
},
"datastore": null,
"parentSnapshot": null,
"currentlyActive": true,
"dateCreated": "2022-01-14T12:57:20Z"
}
}
This endpoint retrieves a specific snapshot.
HTTP Request
GET $serverUrl/api/snapshots/:id
URL Parameters
| Parameter | Description |
|---|---|
| id | ID of the snapshot |
Snapshot an Instance
curl -X PUT "$serverUrl/api/instances/1773/snapshot" \
-H "Authorization: BEARER $accessToken" \
-H "Content-Type: application/json" \
-d '{ "snapshot": {
"name": "snapshot-test",
"description": "A snapshot created via the Morpheus api",
}
}'
The above command returns JSON structure that looks like this:
{
"success": true
}
This endpoint will create a snapshot of an instance. This is done asychronously, so the ID of the snapshot is not returned.
HTTP Request
PUT $serverUrl/api/instances/:id/snapshot
URL Parameters
| Parameter | Description |
|---|---|
| id | ID of the instance |
JSON Snapshot Parameters
These parameters are passed under an object named snapshot.
| Parameter | Default | Description |
|---|---|---|
| name | "{serverName}.{timestamp}" | Optional name for the snapshot being created. |
| description | Optional description for the snapshot |
Import Snapshot of an Instance
curl -X PUT "$serverUrl/api/instances/1/import-snapshot" \
-H "Authorization: BEARER $accessToken" \
-H "Content-Type: application/json" \
-d '{ "storageProviderId": 1
}'
The above command returns JSON structure like this:
{
"success": true
}
It is possible to import a snapshot of an instance. This creates a Virtual Image of the instance as it currently exists.
HTTP Request
PUT $serverUrl/api/instances/:id/import-snapshot
URL Parameters
| Parameter | Description |
|---|---|
| id | ID of the instance |
JSON Parameters
| Parameter | Default | Description |
|---|---|---|
| storageProviderId | null | Optional storage provider to use. |
Revert Instance to Snapshot
curl -X PUT "$serverUrl/api/instances/1/revert-snapshot/1835" \
-H "Authorization: BEARER $accessToken" \
-H "Content-Type: application/json"
The above command returns JSON structure like this:
{
"success": true
}
It is possible to restore an Instance to a snapshot.
HTTP Request
PUT $serverUrl/api/instances/:id/revert-snapshot/:snapshotId
URL Parameters
| Parameter | Description |
|---|---|
| id | ID of the instance |
| :snapshotId | ID of the snapshot |
Delete Snapshot of Instance
curl -X DELETE "$serverUrl/api/snapshots/1835" \
-H "Authorization: BEARER $accessToken" \
-H "Content-Type: application/json"
The above command returns JSON structure like this:
{
"success": true
}
Delete snapshot of instance.
HTTP Request
DELETE $serverUrl/api/snapshots/:id
URL Parameters
| Parameter | Description |
|---|---|
| id | ID of the snapshot |
Delete All Snapshots of Instance Container
curl -X DELETE "$serverUrl/api/instances/54/delete-container-snapshots/403" \
-H "Authorization: BEARER $accessToken" \
-H "Content-Type: application/json"
The above command returns JSON structure like this:
{
"success": true
}
Delete All Snapshots attached to Instance Container.
HTTP Request
DELETE $serverUrl/api/instances/:id/delete-container-snapshots/:containerId
URL Parameters
| Parameter | Description |
|---|---|
| id | ID of instance |
| :containerId | ID of the instance container |
Delete All Snapshots of Instance
curl -X DELETE "$serverUrl/api/instances/54/delete-all-snapshots" \
-H "Authorization: BEARER $accessToken" \
-H "Content-Type: application/json"
The above command returns JSON structure like this:
{
"success": true
}
Delete All Snapshots attached to Instance.
HTTP Request
DELETE $serverUrl/api/instances/:id/delete-all-snapshots
URL Parameters
| Parameter | Description |
|---|---|
| id | ID of the instance |
Create Linked Clone of Instance Snapshot
curl -X PUT "$serverUrl/api/instances/1/linked-clone/1835" \
-H "Authorization: BEARER $accessToken" \
-H "Content-Type: application/json"
The above command returns JSON structure like this:
{
"success": true
}
It is possible to create a linked clone of an Instance Snapshot.
HTTP Request
PUT $serverUrl/api/instances/:id/linked-clone/:snapshotId
URL Parameters
| Parameter | Description |
|---|---|
| id | ID of the instance |
| :snapshotId | ID of the snapshot |
Clone to Image
curl -X PUT "$serverUrl/api/instances/1/clone-image" \
-H "Authorization: BEARER $accessToken" \
-H "Content-Type: application/json" \
-d '{ "templateName": "Example Image", "zoneFolder": "group-v81" }'
The above command returns JSON structure like this:
{
"success": true
}
This endpoint allows creating an image template from an existing instance.
HTTP Request
PUT $serverUrl/api/instances/:id/clone-image
URL Parameters
| Parameter | Description |
|---|---|
| id | ID of the instance |
JSON Parameters
| Parameter | Default | Description |
|---|---|---|
| templateName | Image Template Name. Default is server name + timestamp. | |
| zoneFolder | Zone Folder externalId. This is required for VMware |
Lock an Instance
curl -X PUT "$serverUrl/api/instances/1/lock" \
-H "Authorization: BEARER $accessToken"
The above command returns JSON structure like this:
{
"success": true
}
This will lock the instance. While locked, instances may not be removed.
HTTP Request
PUT $serverUrl/api/instances/:id/lock
URL Parameters
| Parameter | Description |
|---|---|
| id | ID of the instance |
Unlock an Instance
curl -X PUT "$serverUrl/api/instances/1/unlock" \
-H "Authorization: BEARER $accessToken"
The above command returns JSON structure like this:
{
"su