SpotByFlexeraLogo
API docs by Redocly

Spot by Flexera API (1.0)

Download OpenAPI specification:Download

E-mail: support@spot.io

Welcome to the Spot by Flexera OpenAPI Specification. Here you will find REST definitions for all Spot products and platform administration tasks.

The API is hosted at https://api.spotinst.io and requires Bearer Token Authentication.

For more information on how to use the Spot platform, including user guides, developer guides, concepts, and tutorials, see the external Spot Documentation.

https://docs.spot.io/

Organizations

Create User

Create a new user and link it to the creator's organization (the organization ID from the personal token attached to the API call). If the role is a viewer, the user is also linked to the default account for the organization.

Authorizations:
auth
query Parameters
generateToken
boolean
Example: generateToken=true

If true, then the response will include personalAccessToken string

Request Body schema: application/json
email
string

Email

firstName
string

The first name of the user. Note: names cannot include these characters: + = @

lastName
string

The last name of the user. Note: names cannot include these characters: + = @

password
string

Password

role
string

User's role

Responses

Request samples

Content type
application/json
{
  • "firstName": "Test",
  • "lastName": "Test",
  • "email": "test@spot.io",
  • "password": "password1234",
  • "role": "viewer"
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Users

Get all the users of the organization.

Authorizations:
auth

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Policies

Get all the policies of the organization.

Authorizations:
auth

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get User Details

Get all the details of a given user.

Authorizations:
auth
path Parameters
userId
required
string
Example: u-1234abcd

Identifier of a user.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Delete user

Delete a given user(console or programmatic) from organization.

Authorizations:
auth
path Parameters
userId
required
string
Example: u-1234abcd or pu-87654321

Identifier of a user.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

User - Update User Group Mapping

Update the mapping of a given user to user groups

Authorizations:
auth
path Parameters
userId
required
string
Example: u-1234abcd

Identifier of a user.

Request Body schema: application/json
userGroupIds
Array of strings

A list of the user groups to register the given user to (should be existing user groups only)

Responses

Request samples

Content type
application/json
{
  • "userGroupIds": [
    ]
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

User - Update Policy Mapping

Update the mapping of a given user directly to policies

Authorizations:
auth
path Parameters
userId
required
string
Example: u-1234abcd

Identifier of a user.

Request Body schema: application/json
Array of objects

The policies to register under the given user (should be existing policies only)

Array
accountIds
Array of strings

A list of account IDs to register with the assigned under the given user (should be existing accounts only)

policyId
string

A policy ID to register under the given user (should be existing policy only)

Responses

Request samples

Content type
application/json
{
  • "policies": [
    ]
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get User

Get user's account mapping

Authorizations:
auth
query Parameters
userEmail
required
string
Example: userEmail=test@spot.io

Target user email address

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Delete Organization

Delete a Spot Organization. ID of the organization can be obtained from your Spot console via the following link: https://console.spotinst.com/#/settings/organization/general > Note: This cannot be undone. Take caution.

Authorizations:
auth
path Parameters
organizationId
required
string
Example: 606079812345

ID of the organization you would like to delete

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Create Programmatic User

This API creates a new programmatic user (not a human user). Use this API to provide privileges to an application that needs to interface with Spot. Spot returns a token that the programmatic user can use to perform actions with. requires accounts or policies.

Authorizations:
auth
Request Body schema: application/json
Array of objects

All the accounts the programmatic user will have access to. If used - Cannot be empty.

description
string

Brief description of the user.

name
required
string

Name of the programmatic user. Note: names cannot include these characters: + = @

Array of objects

All the policies the programmatic user will have access to. If used - Cannot be empty.

Responses

Request samples

Content type
application/json
{
  • "description": "test programmatic",
  • "name": "testProgrammaticApi",
  • "accounts": [
    ],
  • "policies": [
    ]
}

Response samples

Content type
application/json
{
  • "response": {
    }
}

Create Organization

Create a Spot Organization.

Authorizations:
auth
Request Body schema: application/json
object

Organization

name
string

Provide a name for your organization. The organization name must contain at least one character that is a-z or A-Z

Responses

Request samples

Content type
application/json
{
  • "organization": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Access Policy Actions

Get actions for access policies.

Authorizations:
auth
query Parameters
category
string
Example: category=update

The policy action category that you would like to get the information for

name
string
Example: name=ocean:updateCluster

The policy action Name that you would like to get the information for

resourcePattern
string
Example: resourcePattern=ocean:o-*

The policy action resource pattern that you would like to get the information for

scope
string
Example: scope=account

The policy action scope that you would like to get the information for

service
string
Example: service=ocean

The policy action service that you would like to get the information for

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Create Access Policy

Create an access policy to define the user's permissions more granularly than the role-based permissions.

Authorizations:
auth
Request Body schema: application/json
object

Set access policy settings. Example - Acme, Inc.

description
string

Short description of policy

name
string

Name of the Policy. Note: names cannot include these characters: + = @

object

Set permissions objects list

Responses

Request samples

Content type
application/json
{
  • "policy": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Update Access Policy

Updates an access policy settings.

Authorizations:
auth
path Parameters
policyId
required
string
Example: pol-2344nn

The access policy ID to operate on

Request Body schema: application/json
object

Set access policy settings

name
string

Set access policy name

Responses

Request samples

Content type
application/json
{
  • "policy": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Delete Access Policy

Deletes an access policy settings.

Authorizations:
auth
path Parameters
policyId
required
string
Example: pol-2344nn

The access policy ID to operate on

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

List All User Groups

List all user-groups of your Spot organization

Authorizations:
auth

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Create a new User Group

Create a new user-group of your Spot organization

Authorizations:
auth
Request Body schema: application/json
description
string

user group description

name
string

Name of the user group. Note: names cannot include these characters: + = @

Array of objects

The policies to register under the given group (should be existing policies only)

userIds
Array of strings

The users to register under the created group (should be existing users only)

Responses

Request samples

Content type
application/json
{
  • "name": "Developers",
  • "description": "managing permissions to my group of developers",
  • "userIds": [
    ],
  • "policies": [
    ]
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get User Group Details

Get the details of a user Group

Authorizations:
auth
path Parameters
userGroupId
required
string
Example: ugr-1234abcd

Identifier of a user Group.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Update User Group Details

Update the details of a user Group

Authorizations:
auth
path Parameters
userGroupId
required
string
Example: ugr-1234abcd

Identifier of a user Group.

Request Body schema: application/json
description
string non-empty

user group description

name
string non-empty

user group name

Responses

Request samples

Content type
application/json
{
  • "name": "Developers",
  • "description": "managing permissions to my group of developers"
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Delete User Group

Delete a user Group

Authorizations:
auth
path Parameters
userGroupId
required
string
Example: ugr-1234abcd

Identifier of a user Group.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

User Group - Update User Mapping

Update the mapping of a given user group to users

Authorizations:
auth
path Parameters
userGroupId
required
string
Example: ugr-1234abcd

Identifier of a user Group.

Request Body schema: application/json
userIds
Array of strings

The users to register under the given user group (should be existing users only)

Responses

Request samples

Content type
application/json
{
  • "userIds": [
    ]
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

User Group - Update Policy Mapping

Update the mapping of a given user group to policies

Authorizations:
auth
path Parameters
userGroupId
required
string
Example: ugr-1234abcd

Identifier of a user Group.

Request Body schema: application/json
Array of objects

The policies to register under the given user group (should be existing policies only)

Array
accountIds
Array of strings

A list of accounts to register with the assigned under the given group (should be existing accounts only)

policyId
string

A policy to register under the given group (should be existing policy only)

Responses

Request samples

Content type
application/json
{
  • "policies": [
    ]
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get FinOps Authorization Policies

Get all available FinOps authorization policies.

Authorizations:
auth
query Parameters
paginationKey
string

key used to fetch the next page of items

paginationSize
integer

number of items to include in the response

targetOrganizationId
string

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get FinOps Authorization For User

Get the user-level FinOps authorization configuration for the specified user.

Authorizations:
auth
path Parameters
userId
required
string

The userId to retrieve.

query Parameters
includeChildOrgs
boolean
Default: false

Include the configurations for child organizations.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Update FinOps Authorization For User

Update the FinOps authorization configuration for a user.

Authorizations:
auth
path Parameters
userId
required
string
Request Body schema:
object (userAuthConfigChanges)

The FinOps authorization changes for a user.

Array of objects or null (basicRequestListModification)

List of accounts to add/remove. If user or group already has an existing list of accounts, the requested actions will be applied to this existing list unless resetAccounts is true (which will clear all existing accounts first).

Array of objects or null (costTypeRequestListModification)

List of cost types to add/remove. Cost type applies to all accounts assigned to the user (regardless of how the user has access to the account). If the user already has an existing list of cost types, the requested actions are applied to this existing list unless resetCostTypes is true (which will clear all existing cost types first).

organizationId
string or null

ID of the target Spot organization where the authorization configuration should be applied. Optional: Defaults to the caller's current Spot organization. If specified, the ID must be one of these:

  • The caller's current Spot organization
  • A child Spot organization of the caller's current Spot organization
Array of objects or null (basicRequestListModification)

List of policies to add/remove. If user or group already has an existing list of policies, the requested actions will be applied to this existing list unless resetPolicies is true (which will clear all existing policies first).

resetAccounts
boolean

If true, the existing list of accounts is emptied prior to performing the changes requested.

resetCostTypes
boolean

If true, the existing list of cost types is emptied prior to performing the changes requested.

resetPolicies
boolean

If true, the existing list of policies is emptied prior to performing the changes requested.

Responses

Request samples

Content type
{
  • "authChanges": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Accounts

Update Account

Update information in an account such as the account name and slack channel. To use this command, permissions for organization admin are required. Granular permissions will require access policies with the following actions: setup:updateAccount

Authorizations:
auth
path Parameters
accountId
required
string
Example: act-123456789

The ID of the account you want to update.

Request Body schema: application/json
required
object

Used for updating items in an account.

name
string

The new name of the account. Cannot be null or empty.

slackNotificationChannels
Array of strings

List of strings containing the URLs of the slack channels to be added.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Delete Account

Delete a Spot Account. The Spot Account ID can be obtained from your Spot console via the following link: https://console.spotinst.com/#/settings/account/general . Note This cannot be undone – take caution. Only Organization Admins can perform this action. In case you want to delete your default Spot account which is the account visible when you first log in please contact Support.

Authorizations:
auth
path Parameters
accountId
required
string
Example: act-123456789

The ID of the account you want to delete.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Users

Get all users in the organization, their details, and mapped accounts. Providing the optional account ID parameter will filter out all users not mapped to that account.

Authorizations:
auth
query Parameters
accountId
string
Example: accountId=act-123abc

ID of the account you would like to get retrieve users from

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Assign Users to Accounts

Assign users to accounts in bulk. Only accounts under the creator's own organization are allowed. Creator's organization ID is taken from the personal token attached to the API call.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
One of
Array of assignUsersToAccounts-example2 (object) or assignUsersToAccounts-example3 (object)

Mappings objects include user, accountID and role.

Array
Any of
accountId
string

Account for which to provide the specified user with the specified role.

role
string

Valid values "viewer", "editor". Required on permissionStrategy = ROLE_BASED

userId
string

One of userEmail / userId is required. identify user by its user ID

Responses

Request samples

Content type
application/json
Example
{
  • "mappings": [
    ]
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Update User Permissions

Change the users' permissions for an account (only accounts under the creator's own organization are allowed). Creator's organization ID is taken from the personal token attached to the API call.

Authorizations:
auth
path Parameters
accountId
required
string
Example: act-123abc

ID of the account associated with your token

Request Body schema: application/json
One of
permissionStrategy
string
Default: "ROLE_BASED"

Set the user permissions type, by role or by access policy. Valid values "ROLE_BASED", "POLICY_BASED"

role
string

Valid values "viewer", "editor". Required on permissionStrategy = ROLE_BASED

userId
string

One of userEmail / userId is required. identify user by its user ID

Responses

Request samples

Content type
application/json
Example
{
  • "userId": "u-1234",
  • "permissionStrategy": "POLICY_BASED",
  • "role": "editor"
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Detach User

Detach a user from an account (only accounts under the creator's own organization are allowed). Creator's organization ID is taken from the personal token attached to the API call.

Authorizations:
auth
path Parameters
accountId
required
string
Example: act-123456789

The ID of the account you want to update.

Request Body schema: application/json
userEmail
required
string

Email of the user that is going to be deleted

Responses

Request samples

Content type
application/json
{
  • "userEmail": "test@gmail.com"
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Set Existing User Permissions

Add a user to the account and set its permissions on the account. Creator's organization ID is taken from the personal token attached to the API call.

Authorizations:
auth
path Parameters
accountId
required
string
Example: act-123456789

The ID of the account you want to update.

Request Body schema: application/json
One of
role
string

Valid values - "viewer", "editor". Required on permissionStrategy = ROLE_BASED

userEmail
string

One of userEmail / userId is required. identify user by its user ID

Responses

Request samples

Content type
application/json
Example
{
  • "userEmail": "test@spot.io",
  • "role": "viewer"
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Create Account

Create a Spot account.

Authorizations:
auth
Request Body schema: application/json
object

Account

name
string

Provide a name for your account. The account name must contain at least one character that is a-z or A-Z

Responses

Request samples

Content type
application/json
{
  • "account": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

List Accounts

Get a list of Spot accounts in your organization. When used without any parameters, the provided token must have Organization Admin permissions and the output will contain all the Organization's accounts. Note In case you want to list all the accounts associated with Organization you can use the below request URL without the cloudAccountId parameter, https://api.spotinst.io/setup/account

Authorizations:
auth
query Parameters
cloudAccountId
string
Example: cloudAccountId=634245686616

Will list only the Spot accounts connected to the specified account ID.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

List Access Policies

Get access policy settings.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Set Credentials for AWS

Link a Spot account to an AWS Cloud account.
Please create external id using spot api (see /setup/credentials/aws/externalId)
and use it when creating the AWS role and then call this route with your AWS role's arn to link it to your spot account

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
object

Credentials details

iamRole
required
string

Provide the IAM Role ARN connected to another AWS account 922761411349 and with the latest Spot Policy - https://docs.spot.io/administration/api/spot-policy-in-aws

Responses

Request samples

Content type
application/json
{
  • "credentials": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Create AWS account external id

Create aws account external id
You should use the external id when creating your AWS role for your spot account
and after you create the role you need to call set-aws-credentials Set Credentials for AWS
to link your AWS account with your spot account

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Set Credentials for GCP

Link a Spot account to a GCP Cloud account.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
object

Set service account for credentials

auth_provider_x509_cert_url
auth_uri
string

Authentication uri, Default - https://accounts.google.com/o/oauth2/auth

client_email
string

Email associated with service account

client_id
string

Client ID of service account

client_x509_cert_url
string

Should be in following format - "https://www.googleapis.com/robot/v1/metadata/x509/"

private_key
string

Private key of JSON key created during prerequisites stage

private_key_id
string

Private key ID of JSON key created during prerequisites stage

project_id
string

Name of project in GCP

token_uri
string
type
string

Valid values - service_account

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Validate Credentials for GCP

Validate the credentials for connecting a Spot account to an GCP Cloud account. The validation will test the credentials without actually set it. Please notice to run the set credentials request to perform the set account credentials.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
object

Set service account for credentials

auth_provider_x509_cert_url
auth_uri
string

Authentication uri, Default - https://accounts.google.com/o/oauth2/auth

client_email
string

Email associated with service account

client_id
string

Client ID of service account

client_x509_cert_url
string

Should be in following format - "https://www.googleapis.com/robot/v1/metadata/x509/"

private_key
string

Private key of JSON key created during prerequisites stage

private_key_id
string

Private key ID of JSON key created during prerequisites stage

project_id
string

Name of project in GCP

token_uri
string
type
string

Valid values - service_account

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Set Credentials for Azure

Link a Spot account to an Azure Cloud account. Enter the expiration date of your Azure client secret. Spot can remind you to update before the credentials expire. If your client secret expires, your Azure subscription will disconnect from Spot and prevent Spot from managing your resources.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
clientId
required
string

Set the application ID

clientSecret
required
string

Set the key secret

expirationDate
required
string <date-time>

Set the key secret expiration date

subscriptionId
required
string

Set the subscription ID

tenantId
required
string

Set the directory ID

Responses

Request samples

Content type
application/json
{
  • "clientId": 111111111,
  • "clientSecret": "32431r2431434132",
  • "tenantId": "1321e1e3123er23",
  • "subscriptionId": "234r3141131",
  • "expirationDate": "2025-12-31T23:59:00.000Z"
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Credentials for Azure

Get the credentials connecting a Spot account to an Azure Cloud account.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Validate Credentials for Azure

Validate the credentials for connecting a Spot account to an Azure Cloud account. The validation will test the credentials without actually set it. Please notice to run the set credentials request to perform the set Azure account credentials (https://docs.spot.io/connect-your-cloud-provider/azure-account) .

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
clientId
string

Set the application ID

clientSecret
string

Set the key secret

subscriptionId
string

Set the subscription ID

tenantId
string

Set the directory ID

Responses

Request samples

Content type
application/json
{
  • "clientId": "111111111",
  • "clientSecret": "32431r2431434132",
  • "tenantId": "1321e1e3123er23",
  • "subscriptionId": "234r3141131"
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Setup Cost Intelligence

Sets up and enables Cost Intelligence functionality on a Spot account. The Spot account must already have credentials and be linked to a valid cloud provider account (e.g. AWS account, Azure subscription, etc).

Authorizations:
auth
Request Body schema: application/json
required
object (Account)
accountId
required
string

Spot account ID

Responses

Request samples

Content type
application/json
{
  • "account": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Cost Intelligence Registered Accounts

Get list of Spot accounts where Cost Intelligence has been setup.

Authorizations:
auth
query Parameters
paginationKey
string

Key used to fetch a specific page of items

paginationSize
integer

Number of items to include in the response

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Perform Cost Intelligence Setup Validations

Validate that Cost Intelligence can be setup on the specified Spot Account.

Authorizations:
auth
Request Body schema: application/json
required
object (Account)
accountId
required
string

Spot account ID

Responses

Request samples

Content type
application/json
{
  • "account": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Billing Engine Registered Accounts

Get list of Spot accounts where Billing Engine has been setup.

Authorizations:
auth
query Parameters
paginationKey
string

Key used to fetch a specific page of items

paginationSize
integer

Number of items to include in the response

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Setup Billing Engine

Sets up and enables Billing Engine functionality on a Spot account. The Spot account must already have credentials and be linked to a valid cloud provider account (e.g. AWS account, Azure billing account, etc).

Authorizations:
auth
Request Body schema: application/json
accountId
required
string

Spot Account ID.

(object or null) or (BERegisteredSetupAccountAwsConfig (object or null)) or (BERegisteredSetupAccountAzureConfig (object or null)) or (BERegisteredSetupAccountGcpConfig (object or null))

Configuration for the Billing Engine (e.g. location of the billing data)

Responses

Request samples

Content type
application/json
{
  • "accountId": "act-23432",
  • "config": { }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Perform Billing Engine Setup Validations

Validate that Billing Engine can be setup on the specified Spot Account.

Authorizations:
auth
Request Body schema: application/json
accountId
required
string

Spot Account ID.

(object or null) or (BERegisteredSetupAccountAwsConfig (object or null)) or (BERegisteredSetupAccountAzureConfig (object or null)) or (BERegisteredSetupAccountGcpConfig (object or null))

Configuration for the Billing Engine (e.g. location of the billing data)

Responses

Request samples

Content type
application/json
{
  • "accountId": "act-23432",
  • "config": { }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Ocean AWS

Ocean - Serverless containers for Amazon Web Services (AWS)

Ocean Concepts and Tutorials

Create Cluster

Prerequisites

The Ocean Controller is used to monitor the cluster resources and report back to Ocean. The Ocean Controller is required for Ocean Cloud.

To install the Ocean Controller, complete and run the following script on a machine with the kubectl command line tool installed and configured:

#!/usr/bin/env bash
curl -fsSL http://spotinst-public.s3.amazonaws.com/integrations/kubernetes/cluster-controller/scripts/init.sh | \
SPOTINST_TOKEN=<ENTER YOUR TOKEN HERE> \
SPOTINST_ACCOUNT=<ENTER YOUR SPOTINST ACCOUNT ID HERE> \
SPOTINST_CLUSTER_IDENTIFIER=<ENTER YOUR CLUSTER IDENTIFIER HERE> \
bash
Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
required
object (AWS Cluster)

The object specifying the configuration of the Ocean cluster.

object (auto-scaler)

The automatic scaling mechanism used in Ocean for Kubernetes.

object (Capacity Units)

The overall capability of the Ocean cluster expressed as number of instances and specified with a minimum, a maximum, and a target number of running instances.

required
object (Ocean Compute)

Compute specifications for the Ocean cluster.

controllerClusterId
required
string

Enter the reporting identifier for the Ocean Controller.

object (Logging configuration)
name
required
string

Add a name for the Ocean cluster.

region
required
string

Select the region for the Ocean cluster to run in.

object (Elastigroup Scheduling)

An object used to define times for a task such as a shutdown to be activated.

object (Security)

Object for cluster security features.

object (Ocean Cluster Strategy)

An object defining the cluster strategy with regard to waiting periods and utilization of on-demand and reserved instances.

Responses

Request samples

Content type
application/json
{
  • "cluster": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

List Clusters

List the configurations for all Ocean clusters in the specified account.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Delete Cluster

Delete an existing Ocean cluster.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Cluster

Get the configuration of an existing Ocean cluster.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Update Cluster

All Ocean parameters are updatable, except for region and identifier. This API supports partial updates, so specific fields can be updated separately.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

autoApplyTags
string
Default: "false"
Example: autoApplyTags=true

Option to update instance tags on the fly without rolling the cluster.

Request Body schema: application/json
required
object (AWS Cluster)

The object specifying the configuration of the Ocean cluster.

object (auto-scaler)

The automatic scaling mechanism used in Ocean for Kubernetes.

object (Capacity Units)

The overall capability of the Ocean cluster expressed as number of instances and specified with a minimum, a maximum, and a target number of running instances.

object (Ocean Compute)

Compute specifications for the Ocean cluster.

controllerClusterId
string

Enter the reporting identifier for the Ocean Controller.

object (Logging configuration)
name
string

Add a name for the Ocean cluster.

region
string

Select the region for the Ocean cluster to run in.

object (Elastigroup Scheduling)

An object used to define times for a task such as a shutdown to be activated.

object (Security)

Object for cluster security features.

object (Ocean Cluster Strategy)

An object defining the cluster strategy with regard to waiting periods and utilization of on-demand and reserved instances.

Responses

Request samples

Content type
application/json
{
  • "cluster": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Heartbeat Status

Get the heartbeat status of the Ocean Controller for the cluster.
The response returns the heartbeat status and the last heartbeat timestamp.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Fetch Elastilog

Fetch the log of an Ocean cluster.

Authorizations:
auth
path Parameters
clusterIdentifier
required
string
Example: o-6e3819ae

The reporting identifier of the Ocean Controller.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

fromDate
required
string

Beginning date value using either the date format "yyyy-mm-dd; 2016-11-20" or ms "1494751821472".

limit
integer <= 1000
Default: 500
Example: limit=200

Maximum number of lines to extract in a response.

resourceId
string
Example: resourceId=i-12345678

Filter extracted log entries for a specific resource identifier. Default: Null

severity
string
Default: "ALL"
Enum: "ALL" "INFO" "DEBUG" "ERROR" "WARN"
Example: severity=INFO

Severity of log entries to extract.

toDate
required
string

End date value using either the date format "yyyy-mm-dd; 2016-11-20" or ms "1494751821472".

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Import ASG To Ocean Cluster

Create an Ocean configuration according to an AWS autoscaling group (ASG) configuration.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

autoScalingGroupName
required
string
Example: autoScalingGroupName=myAutoScalingGroup

The ASG name.

region
required
string
Example: region=us-east-1

Region name of the ASG.

Request Body schema: application/json
object

The object specifying the configuration of the VNG.

instanceTypes
Array of strings

List of possible instance types for the cluster.

Responses

Request samples

Content type
application/json
{
  • "cluster": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Fetch Right Sizing Recommendations

Get right-sizing recommendations for an Ocean cluster and filter them according to namespace or label.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
object

Optional - may be null.

object

Optional - may be null.

namespaces
Array of strings

Optional - may be null. If exists - should contain at least 1 item.

Responses

Request samples

Content type
application/json
{
  • "filter": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Instance Types Filters Simulation

Returns all instances types that match the given filters. These instance types will be used if the cluster is configured with these filters.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
required
object (InstanceTypesFilters)

List of filters. The Instance types that match with all filters compose the Ocean's whitelist parameter. Cannot be configured together with whitelist/blacklist.

architectures
Array of strings
Items Enum: "i386" "x86_64" "arm64"

The filtered instance types will support at least one of the architectures from this list.

categories
Array of strings
Items Enum: "Accelerated_computing" "Compute_optimized" "General_purpose" "Memory_optimized" "Storage_optimized"

The filtered instance types will belong to one of the categories types from this list.

diskTypes
Array of strings
Items Enum: "NVMe" "EBS" "SSD" "HDD"

The filtered instance types will have one of the disk type from this list.

excludeFamilies
Array of strings

Types belonging to a family from the ExcludeFamilies will not be available for scaling (asterisk wildcard is also supported). For example, C* will exclude instance types from these families: c5, c4, c4a, etc.

excludeMetal
boolean
Default: false

In case excludeMetal is set to true, metal types will not be available for scaling.

hypervisor
Array of strings
Items Enum: "nitro" "xen"

The filtered instance types will have a hypervisor type from this list.

includeFamilies
Array of strings

Types belonging to a family from the IncludeFamilies will be available for scaling (asterisk wildcard is also supported). For example, C* will include instance types from these families: c5, c4, c4a, etc.

isEnaSupported
boolean

Ena is supported or not.

maxGpu
integer >= 1

Maximum total number of GPUs.

maxMemoryGiB
number <double> >= 0

Maximum amount of Memory (GiB).

maxNetworkPerformance
integer >= 1

Maximum Bandwidth in Gib/s of network performance.

maxVcpu
integer >= 1

Maximum number of vcpus available.

minEnis
integer >= 0

Minimum number of network interfaces (ENIs).

minGpu
integer >= 0

Minimum total number of GPUs.

minMemoryGiB
number <double> >= 0

Minimum amount of Memory (GiB).

minNetworkPerformance
integer >= 0

Minimum Bandwidth in Gib/s of network performance.

minVcpu
integer >= 0

Minimum number of vcpus available.

rootDeviceTypes
Array of strings
Items Enum: "ebs" "instance-store"

The filtered instance types will have a root device types from this list.

virtualizationTypes
Array of strings
Items Enum: "hvm" "paravirtual"

The filtered instance types will support at least one of the virtualization types from this list.

Responses

Request samples

Content type
application/json
{
  • "filters": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Allowed Instance Types

Return the list of the allowed Ocean cluster instance types.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Attach Load Balancers

Add new load balancers to the existing load balancers on the Ocean Cluster.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
required
Array of objects (ocean-lb)

Load balancers to add to the Ocean cluster.

Array
arn
string

If type is "TARGET_GROUP" then an ARN is required. Otherwise is not allowed.

name
string

If type is "CLASSIC" then a name is required. Otherwise is not allowed.

type
required
string
Enum: "CLASSIC" "TARGET_GROUP"

Type of load balancer to use.

Responses

Request samples

Content type
application/json
{
  • "loadBalancers": [
    ]
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Detach Load Balancers

Remove load balancers from the existing load balancers on the Ocean Cluster.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
required
Array of objects (ocean-lb)

Load balancers to remove from the Ocean cluster.

Array
arn
string

If type is "TARGET_GROUP" then an ARN is required. Otherwise is not allowed.

name
string

If type is "CLASSIC" then a name is required. Otherwise is not allowed.

type
required
string
Enum: "CLASSIC" "TARGET_GROUP"

Type of load balancer to use.

Responses

Request samples

Content type
application/json
{
  • "loadBalancers": [
    ]
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Upgrade Elastigroup To Ocean

Upgrade an Elastigroup with Kubernetes integration to Ocean for Kubernetes cluster.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

groupId
required
string

Elastigroup identifier

Responses

Response samples

Content type
application/json
{
  • "kind": "spotinst:ocean:aws:k8s",
  • "items": {
    }
}

Initiate Roll

Roll an entire Ocean cluster or roll subsets of the cluster by specifying launchSpecIds or instanceIds. Performing this request will start the roll immediately and run it in defined batches. Note that the first response for a successful request will indicate the start of a roll. In order to check the status of a roll, you can use the GET Roll API.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
One of
object
batchMinHealthyPercentage
integer
Default: 50

Indicates the threshold of minimum healthy instances in single batch. If the amount of healthy instances in single batch is under the threshold, the cluster roll will fail. If exists, the parameter value will be in range of 1-100. In case of null as value, the default value in the backend will be 50%. Value of param should represent the number in percentage (%) of the batch.

batchSizePercentage
integer

Value as a percent to set the size of a batch in a roll. Valid values are 0-100.

comment
string

Add a comment description for the roll. The comment is limited to 256 chars.

respectPdb
boolean
Default: false

During the roll, if the parameter is set to true we honor PDB during the instance replacement.

Responses

Request samples

Content type
application/json
Example
{
  • "roll": {
    }
}

Response samples

Content type
application/json
{
  • "id": "scr-5aaf854e",
  • "scope": "Cluster",
  • "status": "IN_PROGRESS",
  • "currentBatch": 1,
  • "numOfBatches": 5,
  • "comment": "This is why I deployed my cluster.",
  • "progress": {
    },
  • "oceanId": "o-12e31234",
  • "instanceIds": [
    ],
  • "launchSpecIds": [
    ],
  • "respectPdb": true,
  • "batchMinHealthyPercentage": 100,
  • "createdAt": "2019-03-24T15:46:09.000Z",
  • "updatedAt": "2019-03-24T15:46:09.000Z"
}

List Rolls

Get status for all rolls of an Ocean cluster.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-1abcd124

The identifier of the Ocean cluster

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "status": {
    },
  • "kind": "spotinst:ocean:aws:k8s:cluster:roll",
  • "items": [
    ]
}

Update Roll

Update a roll of an Ocean cluster.

Performing the request will stop the next batch in a roll.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-1abcd124

The identifier of the Ocean cluster

ROLL_ID
required
string
Example: scr-12345abc

Ocean cluster roll identifier

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
required
object

Object that specifies the parameters required to initiate a roll (also called a deployment).

status
required
string
Value: "STOPPED"

Set status of a roll. Valid values: "STOPPED"

Responses

Request samples

Content type
application/json
{
  • "roll": {
    }
}

Response samples

Content type
application/json
{
  • "id": "scr-5aaf854e",
  • "scope": "Cluster",
  • "status": "STOPPED",
  • "currentBatch": 1,
  • "numOfBatches": 5,
  • "progress": {
    },
  • "oceanId": "o-12e31234",
  • "respectPdb": true,
  • "batchMinHealthyPercentage": 100,
  • "createdAt": "2019-03-24T15:46:09.000Z",
  • "updatedAt": "2019-03-24T15:46:09.000Z"
}

Get Roll

Get status for a roll of an Ocean cluster.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-1abcd124

The identifier of the Ocean cluster

ROLL_ID
required
string
Example: scr-12345abc

Ocean Cluster Roll identifier

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "id": "scr-5aaf854e",
  • "scope": "Cluster",
  • "status": "IN_PROGRESS",
  • "currentBatch": 1,
  • "numOfBatches": 5,
  • "comment": "This is why I deployed my cluster.",
  • "progress": {
    },
  • "oceanId": "o-12e31234",
  • "instanceIds": [
    ],
  • "launchSpecIds": [
    ],
  • "respectPdb": true,
  • "batchMinHealthyPercentage": 100,
  • "createdAt": "2019-03-24T15:46:09.000Z",
  • "updatedAt": "2019-03-24T15:46:09.000Z"
}

Get Cluster Nodes

Get nodes data of an Ocean cluster.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

instanceId
string
Example: instanceId=i-123

Get a specific node by instance id.

launchSpecId
string
Example: launchSpecId=ols-123abc

Ocean cluster Virtual Node Group identifier.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Detach Instances

Detach instances from your Ocean cluster.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
instancesToDetach
required
Array of strings

Array of instance identifiers to be detached.

shouldDecrementTargetCapacity
boolean

Determines whether the Ocean cluster's target capacity should be decremented.

shouldTerminateInstances
boolean

Determines whether the detached EC2 instances should be terminated or not.

Responses

Request samples

Content type
application/json
{
  • "instancesToDetach": [
    ],
  • "shouldTerminateInstances": true,
  • "shouldDecrementTargetCapacity": false
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Cluster Aggregated Detailed Costs

Provides Kubernetes cluster resource usage and costs over a time interval which can be grouped and/or filtered by label/annotaion.
For example - application name (webapp, backend), environment (production, staging), version etc.
The response will contain a breakdown of the cluster resource costs($) in terms of compute (CPU, memory), storage (block, file, rootVolume). The response will group the cluster usage costs based on preselected default of application namespace or user selected label or annotation.
Within the group, resource costs are broken down per resource kind (Deployment, DaemonSet etc.).

Time Rounding Down: The CostAnalysis API applies rounding down to the hours provided during the call.
For example, the value 1707004799099 (In GMT) representing Saturday, February 3, 2024, 23:59:59.099 is rounded down to Saturday, February 3, 2024, 23:00:00.000, resulting in the omission of one hour of cost.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
endTime
required
string

End date value using either the date format "yyyy-MM-dd'T'HH:mm:ss'Z'" or ms "1494751821472".

object

Describe how to filter the costs. Optional field.

groupBy
string
Default: "namespace"
Enum: "namespace" "namespace.label.${labelKey}" "resource.label.${labelKey}" "resource.annotation.${annotationKey}" "namespace.annotation.${annotationKey}"

The parameter we want to group the costs by.

startTime
required
string

Beginning date value using either the date format "yyyy-MM-dd'T'HH:mm:ss'Z'" or ms "1494751821472".

Responses

Request samples

Content type
application/json
{
  • "startTime": "2018-06-20T11:35:02.745Z",
  • "endTime": "2018-06-22T11:30:01.745Z",
  • "groupBy": "namespace.label.env",
  • "filter": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Cluster Aggregated Summary Costs

Provides Kubernetes cluster summary usage and costs over a time interval which can be grouped and/or filtered by label/annotaion,
for example - application name (webapp, backend), environment (production, staging), version etc.
The response will contain a breakdown of the cluster resource costs($) in terms of compute (CPU, memory), storage (block, file, rootVolume). The response will group the cluster usage costs based on preselected default of application namespace or user selected label or annotation.

Time Rounding Down: The CostAnalysis API applies rounding down to the hours provided during the call.
For example, the value 1707004799099 (In GMT) representing Saturday, February 3, 2024, 23:59:59.099 is rounded down to Saturday, February 3, 2024, 23:00:00.000, resulting in the omission of one hour of cost.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
endTime
required
string

End date value using either the date format "yyyy-MM-dd'T'HH:mm:ss'Z'" or ms "1494751821472".

object

Describe how to filter the costs. Optional field.

groupBy
string
Default: "namespace"
Enum: "namespace" "namespace.label.${labelKey}" "resource.label.${labelKey}" "resource.annotation.${annotationKey}" "namespace.annotation.${annotationKey}"

The parameter we want to group the costs by.

startTime
required
string

Beginning date value using either the date format "yyyy-MM-dd'T'HH:mm:ss'Z'" or ms "1494751821472".

Responses

Request samples

Content type
application/json
{
  • "startTime": "2018-06-20T11:35:02.745Z",
  • "endTime": "2018-06-22T11:30:01.745Z",
  • "groupBy": "namespace.label.env",
  • "filter": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Initiate EKS AMI Auto Update

Update the Ocean EKS cluster's VNGs with the latest image or the image matching the control plane's version after upgrading, by specifying ‘patch' or 'minorVersion’. Performing this request will update the VNGs with new AMI if available, and run a cluster roll if set. If the response is successful, the old and new AMIs will be included in the response along with the updated VNGs. If a cluster roll is set in the request, the first response for a successful request will indicate the start of a roll. In order to check the status of the roll, you can use the GET Roll API.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
object
applyRoll
boolean
Default: false

This parameter is optional. When the AMI is updated according to the configuration set, a cluster roll can be triggered.

object

Cluster roll configuration.

minorVersion
boolean
Default: false

When set to 'true', the auto-update process will update the VNGs’ AMI with the AMI to match the Kubernetes control plane version. Either "patch" or "minorVersion" must be true.

patch
boolean
Default: false

When set to 'true', the auto-update process will update the VNGs’ images with the latest security patches. Either "patch" or "minorVersion" must be true.

Responses

Request samples

Content type
application/json
{
  • "amiAutoUpdate": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Create Virtual Node Group

Create a Virtual Node Group.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

initialNodes
integer
Default: null
Example: initialNodes=1

When set to an integer greater than 0, a corresponding number of nodes will be launched from the virtual node group created.

Request Body schema: application/json
required
object (oceanClusterLaunchSpecWithMetadata)

AWS Cluster Virtual Node Group (VNG).

associatePublicIpAddress
boolean
Default: false

Configure public IP address allocation.

object

Object specifying the automatic scaling of an Ocean VNG.

Array of objects

Block devices that are exposed to the instance. You can specify virtual devices and EBS volumes.
This parameter and rootVolumeSize cannot be in the spec at the same time.
This parameter can be null, but if not null, it must contain at least one block device.

object

Assign an Elastic IP to the instances launched by the Virtual Node Group. Can be null.

object
object (oceanGpuConfiguration)

GPU configuration

object (auto-scaler)

The instance profile iamRole object.

imageId
string

Set image identifier. Can be null.

Array of objects (Image object, containing the id of the image used to launch instances.)

An array of image objects.

  • You can configure VNG with either the imageId or images objects, but not both simultaneously.
  • For each architecture type (amd64, arm64) only one AMI is allowed.
  • Valid values: null, or an array with at least one element
object (instanceMetadataOptions)

Ocean instance metadata options object for IMDSv2.

object (instanceStorePolicy)

Determines the utilization of instance store volumes. If not defined, instance store volumes will not be used.

instanceTypes
Array of strings

A list of instance types allowed to be provisioned for pods pending for the Virtual Node Group.
The list overrides the list defined for the Ocean cluster. Can be null.

object (InstanceTypesFilters)

List of instance types filters. The instance types that match with all filters compose the Virtual Node Group's instanceTypes parameter.
The architectures that come from the Virtual Node Group's images will be taken into account when using this parameter.
Cannot be configured together with Virtual Node Group's instanceTypes and with the Cluster's whitelist/blacklist/filters.

Array of objects

An array of labels to add to the VNG nodes. Only custom user labels are allowed, and not Kubernetes built-in labels or Spot internal labels.

name
string

Set Virtual Node Group name.

oceanId
required
string

The Ocean cluster identifier. Required for Virtual Node Group creation.

preferredOnDemandTypes
Array of strings

When Ocean scales up instances, it takes your preferred types into consideration while maintaining a variety of machine types running for optimized distribution.

preferredSpotTypes
Array of strings

When Ocean scales up instances, it takes your preferred types into consideration while maintaining a variety of machine types running for optimized distribution. Learn More

reservedENIs
integer
Default: 0

Specifies the count of ENIs to reserve per instance type for scaling purposes.

object
restrictScaleDown
boolean

When set to “True”, VNG nodes will be treated as if all pods running have the restrict-scale-down label. Therefore, Ocean will not scale nodes down unless empty.

rootVolumeSize
integer

Set root volume size (in GB). This field and blockDeviceMappings cannot be used in the same specification.

object (Ocean Scheduling)

An object used to define scheduled tasks such as a manual headroom update.

securityGroupIds
Array of strings

Set security groups. Each element in the array is a security group identifier.

Array of objects

Temporary taints applied to a node during its initialization phase. For a startup taint to work, it must also be set as a regular taint in the userData for the VNG.

object

Similar to a strategy for an Ocean cluster, but applying only to a virtual node group.

subnetIds
Array of strings

Set subnets in Virtual Node Group. Each element in the array is a subnet identifier.

Array of objects

List of kay-value pairs of tags.

Array of objects

Add taints to Virtual Node Group.

userData
string

Set user data script in base 64 encoded MIME.

Responses

Request samples

Content type
application/json
{
  • "launchSpec": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

List Virtual Node Groups

List the configurations of all virtual node groups for the cluster.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

oceanId
string
Example: oceanId=o-12345abc

Identifier of the Ocean cluster.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Delete Virtual Node Group

Delete a specified Virtual Node Group in an Ocean cluster.

Authorizations:
auth
path Parameters
launchSpecId
required
string

Ocean cluster Virtual Node Group identifier.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

deleteNodes
boolean
Default: false
Example: deleteNodes=true

When set to "true", all instances belonging to the deleted Virtual Node Group will be drained, detached, and terminated.

forceDelete
boolean
Default: null
Example: forceDelete=true

When set to "true", delete even if it is the only custom Virtual Node Group remaining, and default Virtual Node Group has useAsTemlateOnly = true.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Update Virtual Node Group

Update Virtual Node Group.

Authorizations:
auth
path Parameters
launchSpecId
required
string

Ocean cluster Virtual Node Group identifier.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

autoApplyTags
boolean
Default: false
Example: autoApplyTags=true

Optionally update resource tags on the fly without performing a roll.

Request Body schema: application/json
required
object (oceanClusterLaunchSpec)

AWS Cluster Virtual Node Group (VNG).

associatePublicIpAddress
boolean
Default: false

Configure public IP address allocation.

object

Object specifying the automatic scaling of an Ocean VNG.

Array of objects

Block devices that are exposed to the instance. You can specify virtual devices and EBS volumes.
This parameter and rootVolumeSize cannot be in the spec at the same time.
This parameter can be null, but if not null, it must contain at least one block device.

object

Assign an Elastic IP to the instances launched by the Virtual Node Group. Can be null.

object
object (oceanGpuConfiguration)

GPU configuration

object (auto-scaler)

The instance profile iamRole object.

imageId
string

Set image identifier. Can be null.

Array of objects (Image object, containing the id of the image used to launch instances.)

An array of image objects.

  • You can configure VNG with either the imageId or images objects, but not both simultaneously.
  • For each architecture type (amd64, arm64) only one AMI is allowed.
  • Valid values: null, or an array with at least one element
object (instanceMetadataOptions)

Ocean instance metadata options object for IMDSv2.

object (instanceStorePolicy)

Determines the utilization of instance store volumes. If not defined, instance store volumes will not be used.

instanceTypes
Array of strings

A list of instance types allowed to be provisioned for pods pending for the Virtual Node Group.
The list overrides the list defined for the Ocean cluster. Can be null.

object (InstanceTypesFilters)

List of instance types filters. The instance types that match with all filters compose the Virtual Node Group's instanceTypes parameter.
The architectures that come from the Virtual Node Group's images will be taken into account when using this parameter.
Cannot be configured together with Virtual Node Group's instanceTypes and with the Cluster's whitelist/blacklist/filters.

Array of objects

An array of labels to add to the VNG nodes. Only custom user labels are allowed, and not Kubernetes built-in labels or Spot internal labels.

name
string

Set Virtual Node Group name.

preferredOnDemandTypes
Array of strings

When Ocean scales up instances, it takes your preferred types into consideration while maintaining a variety of machine types running for optimized distribution.

preferredSpotTypes
Array of strings

When Ocean scales up instances, it takes your preferred types into consideration while maintaining a variety of machine types running for optimized distribution. Learn More

reservedENIs
integer
Default: 0

Specifies the count of ENIs to reserve per instance type for scaling purposes.

object
restrictScaleDown
boolean

When set to “True”, VNG nodes will be treated as if all pods running have the restrict-scale-down label. Therefore, Ocean will not scale nodes down unless empty.

rootVolumeSize
integer

Set root volume size (in GB). This field and blockDeviceMappings cannot be used in the same specification.

object (Ocean Scheduling)

An object used to define scheduled tasks such as a manual headroom update.

securityGroupIds
Array of strings

Set security groups. Each element in the array is a security group identifier.

Array of objects

Temporary taints applied to a node during its initialization phase. For a startup taint to work, it must also be set as a regular taint in the userData for the VNG.

object

Similar to a strategy for an Ocean cluster, but applying only to a virtual node group.

subnetIds
Array of strings

Set subnets in Virtual Node Group. Each element in the array is a subnet identifier.

Array of objects

List of kay-value pairs of tags.

Array of objects

Add taints to Virtual Node Group.

userData
string

Set user data script in base 64 encoded MIME.

Responses

Request samples

Content type
application/json
{
  • "launchSpec": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Virtual Node Group

Authorizations:
auth
path Parameters
launchSpecId
required
string

Ocean cluster Virtual Node Group identifier.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Instance Types Filters Simulation For Virtual Node Group

Returns all instance types that match the given filters. These instance types will be used if the Virtual Node Group is configured with these filters.

Authorizations:
auth
path Parameters
launchSpecId
required
string

Ocean cluster Virtual Node Group identifier.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
required
object (InstanceTypesFilters)

List of instance types filters. The instance types that match with all filters compose the Virtual Node Group's instanceTypes parameter.
The architectures that come from the Virtual Node Group's images will be taken into account when using this parameter.
Cannot be configured together with Virtual Node Group's instanceTypes and with the Cluster's whitelist/blacklist/filters.

categories
Array of strings
Items Enum: "Accelerated_computing" "Compute_optimized" "General_purpose" "Memory_optimized" "Storage_optimized"

The filtered instance types will belong to one of the categories types from this list.

diskTypes
Array of strings
Items Enum: "NVMe" "EBS" "SSD" "HDD"

The filtered instance types will have one of the disk type from this list.

excludeFamilies
Array of strings

Types belonging to a family from the ExcludeFamilies will not be available for scaling (asterisk wildcard is also supported). For example, C* will exclude instance types from these families: c5, c4, c4a, etc.

excludeMetal
boolean
Default: false

In case excludeMetal is set to true, metal types will not be available for scaling.

hypervisor
Array of strings
Items Enum: "nitro" "xen"

The filtered instance types will have a hypervisor type from this list.

includeFamilies
Array of strings

Types belonging to a family from the IncludeFamilies will be available for scaling (asterisk wildcard is also supported). For example, C* will include instance types from these families: c5, c4, c4a, etc.

isEnaSupported
boolean

Ena is supported or not.

maxGpu
integer >= 1

Maximum total number of GPUs.

maxMemoryGiB
number >= 0

Maximum amount of Memory (GiB).

maxNetworkPerformance
integer >= 1

Maximum Bandwidth in Gib/s of network performance.

maxVcpu
integer >= 1

Maximum number of vcpus available.

minEnis
integer >= 0

Minimum number of network interfaces (ENIs).

minGpu
integer >= 0

Minimum total number of GPUs.

minMemoryGiB
number >= 0

Minimum amount of Memory (GiB).

minNetworkPerformance
integer >= 0

Minimum Bandwidth in Gib/s of network performance.

minVcpu
integer >= 0

Minimum number of vcpus available.

rootDeviceTypes
Array of strings
Items Enum: "ebs" "instance-store"

The filtered instance types will have a root device types from this list.

virtualizationTypes
Array of strings
Items Enum: "hvm" "paravirtual"

The filtered instance types will support at least one of the virtualization types from this list.

Responses

Request samples

Content type
application/json
{
  • "instanceTypesFilters": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Allowed Instance Types By Filters For Virtual Node Group

Returns the Virtual Node Group's instance types when instance types filters is set.

Authorizations:
auth
path Parameters
launchSpecId
required
string

Ocean cluster Virtual Node Group identifier.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Import ASG To Ocean Virtual Node Group

Returns an Ocean Virtual Node Group (VNG) configuration in a given AWS autoscaling group (ASG). The returned value ("Imported VNG") can then be used as input to the Create Virtual Node Group API in order to create an actual VNG in your Ocean cluster.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

autoScalingGroupName
required
string
Example: autoScalingGroupName=myAutoScalingGroup

The ASG name.

oceanId
required
string
Example: oceanId=o-12345abc

Identifier of the Ocean cluster.

Request Body schema: application/json
object

The object specifying the configuration of the VNG.

Array of objects

An array of labels to add to the VNG nodes. Only custom user labels are allowed, and not Kubernetes built-in labels or Spot internal labels.

name
string

Set Virtual Node Group name.

Array of objects

Add taints to Virtual Node Group.

Responses

Request samples

Content type
application/json
{
  • "launchSpec": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Import EKS Cluster Node Group To Ocean Virtual Node Group

  • Returns an Ocean Virtual Node Group (VNG) configuration based on a given AWS EKS Cluster Node Group. The returned value ("Imported VNG") can then be used as input to the Create Virtual Node Group API in order to create an actual VNG in your Ocean cluster.
  • Notes:
    • Make sure to have the necessary permissions in your Spot policy: eks:ListNodegroups, eks:DescribeNodegroup. Click here for the full Spot policy.
    • Exactly one of region or oceanId must be supplied as query parameters.
Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

eksClusterName
required
string
Example: eksClusterName=MyEksCluster

Cluster name of the EKS cluster.

eksNodeGroupName
required
string
Example: eksNodeGroupName=MyEksClusterNodeGroup

Node group name to import.

oceanId
string
Example: oceanId=o-12345abc

Identifier of the Ocean cluster.

region
string
Example: region=us-east-1

Region name of the EKS cluster's node group.

Request Body schema: application/json
object

The object specifying the configuration of the VNG.

Array of objects

An array of labels to add to the VNG nodes. Only custom user labels are allowed, and not Kubernetes built-in labels or Spot internal labels.

name
string

Set Virtual Node Group name.

Responses

Request samples

Content type
application/json
{
  • "launchSpec": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Launch Nodes in VNG

Launch nodes in Virtual Node Group.

Authorizations:
auth
path Parameters
launchSpecId
required
string

Ocean cluster Virtual Node Group identifier.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
required
object (Ocean AWS Virtual Node Group Launch Request)

Object specifying the details for the launch request.

amount
required
integer

The number of nodes to launch.

Responses

Request samples

Content type
application/json
{
  • "launchRequest": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Create Extended Resource Definition

Creates an Ocean extended resource definition entity.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
required
object (Ocean Extended Resource Definition)

The Ocean extended resource definition.

mapping
required
object (AWS mapping)

A mapping between AWS instanceType or * as default and its value for the given extended resource.

name
required
string

The extended resource name as should be requested by your pods and registered to the nodes. Cannot be updated.
The name should be a valid Kubernetes extended resource name.

Responses

Request samples

Content type
application/json
{
  • "extendedResourceDefinition": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

List Extended Resource Definitions

List the configurations for all Ocean extended resource definitions in the specified account.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Extended Resource Definition

Get the configurations for a specified Ocean extended resource definition.

Authorizations:
auth
path Parameters
oceanExtendedResourceDefinitionId
required
string
Example: erd-12345abc

Identifier of the Ocean extended resource definition.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Update Extended Resource Definition

Only the mapping parameter is updatable for extended resource definition.

Authorizations:
auth
path Parameters
oceanExtendedResourceDefinitionId
required
string
Example: erd-12345abc

Identifier of the Ocean extended resource definition.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
required
object (Ocean Extended Resource Definition)

The Ocean extended resource definition.

mapping
required
object (AWS mapping)

A mapping between AWS instanceType or * as default and its value for the given extended resource.

name
required
string

The extended resource name as should be requested by your pods and registered to the nodes. Cannot be updated.
The name should be a valid Kubernetes extended resource name.

Responses

Request samples

Content type
application/json
{
  • "extendedResourceDefinition": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Delete Extended Resource Definition

Delete a specified Ocean extended resource definition.

Authorizations:
auth
path Parameters
oceanExtendedResourceDefinitionId
required
string
Example: erd-12345abc

Identifier of the Ocean extended resource definition.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Migration Discovery

Get information about nodes which can be migrated into Ocean.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

shouldFetchPods
boolean
Example: shouldFetchPods=true

Should fetch data about running pods for each node.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Create Migration

Create a migration for a given existing instances.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
required
object

Migration update configuration.

batchSizePercentage
required
integer [ 1 .. 50 ]

Indicates (in percentage) the batch size of the migration (meaning, how many nodes to migrate in each batch).
Cannot be null.

forcePodEvictionOnPdbFailure
required
boolean

Ocean will force the Pod eviction from the instance, even if the distributed budget is not satisfied.

instanceIds
required
Array of strings

A list of instance ids that should be migrated to the Ocean cluster.

shouldEvictStandAlonePods
required
boolean

Ocean will terminate pods that do not belong to a Kubernetes deployment. This means that you would need to launch the pod manually (after the migration) due to the fact that there is no object that would do it automatically.

shouldTerminateDrainedNodes
required
boolean

Ocean will terminate the old instances once the pods that reside on them are migrated, and the old instances are fully drained.

Responses

Request samples

Content type
application/json
{
  • "migration": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

List Migrations summary

Get summary of migrations history for an Ocean cluster.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Migration Status

Get Migration full info and status for an Ocean cluster.

Authorizations:
auth
path Parameters
migrationId
required
string
Example: owm-6e3819ae

The migration identifier of a specific migration.

oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Stop Migration

Stop an ongoing Workload Migration.

Authorizations:
auth
path Parameters
migrationId
required
string
Example: owm-6e3819ae

The migration identifier of a specific migration.

oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
required
object

Migration update configuration.

shouldTerminateDrainedNodes
boolean
Default: false

Ocean will terminate the old instances once the pods that reside on them are migrated, and the old instances are fully drained.

state
required
string

The only allowed state to update is to "STOPPED". This state will stop a running migration.

Responses

Request samples

Content type
application/json
{
  • "migration": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Ocean ECS

Ocean - Serverless containers for Amazon Elastic Container Service (ECS)

Ocean Concepts and Tutorials

List Clusters

Get the configurations for all Ocean clusters in the specified account.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Create Cluster

Create a new Ocean ECS cluster in the specified account.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
required
object (ECS Ocean)
object (Ocean Autoscaler)

The Ocean ECS Autoscaler.

object (Capacity Units)

Capacity specifications for the Ocean cluster.

clusterName
required
string

ECS cluster name.

object (Ocean Compute)
object (Logging configuration)
name
required
string

Add a name for the Ocean cluster.

region
required
string

Select the region for the Ocean cluster to run in.

object (Ocean Scheduling)

An object used to define times for a task such as a shutdown to be activated.

object (Ocean Strategy)

Strategy Configuration of the Ocean cluster.

Responses

Request samples

Content type
application/json
{
  • "cluster": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Cluster

Get the configurations for a specified Ocean cluster.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Update Cluster

All Ocean parameters are updatable, excluding Region and ID. This API supports partial updates, so specific fields can be updated separately.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

autoApplyTags
boolean
Default: false
Example: autoApplyTags=true

Optionally update resource tags on the fly without performing a roll.

Request Body schema: application/json
required
object (ECS Ocean)
object (Ocean Autoscaler)

The Ocean ECS Autoscaler.

object (Capacity Units)

Capacity specifications for the Ocean cluster.

clusterName
string

ECS cluster name.

object (Ocean Compute)
object (Logging configuration)
name
string

Add a name for the Ocean cluster.

object (Ocean Scheduling)

An object used to define times for a task such as a shutdown to be activated.

object (Ocean Strategy)

Strategy Configuration of the Ocean cluster.

Responses

Request samples

Content type
application/json
{
  • "cluster": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Delete Cluster

Delete a specified Ocean cluster.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Import Cluster

Create Ocean cluster object from an existing ECS cluster with at least one container instance to be used as input for create cluster.
Import the configuration from the latest instance id launched with in the cluster (out of the first batch of 100 instances ECS returns).
This route will not register the ECS cluster to Ocean.

Authorizations:
auth
path Parameters
EcsClusterName
required
string
Example: ecsName

ECS Cluster name

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
instanceId
string

Indicate the container instance id that the configuration will be taken from. This is an optional field

name
string

The name for the new Ocean cluster object.
If the name is not provided, the default will be Ocean_{EcsClusterName}

region
required
string

The region that the ECS cluster is running at.

Responses

Request samples

Content type
application/json
{
  • "region": "us-east-1",
  • "name": "oceanName",
  • "instanceId": "i-123456789abcdefgh"
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Fetch Elastilog

Get the log of an Ocean Cluster.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

fromDate
required
string

Beginning date value using either the date format "yyyy-mm-dd; 2016-11-20" or ms "1494751821472".

limit
integer <= 1000
Default: 500
Example: limit=200

Maximum number of lines to extract in a response.

resourceId
string
Example: resourceId=i-12345678

Filter extracted log entries for a specific resource identifier. Default: Null

severity
string
Default: "ALL"
Enum: "ALL" "INFO" "DEBUG" "ERROR" "WARN"
Example: severity=INFO

Severity of log entries to extract.

toDate
required
string

End date value using either the date format "yyyy-mm-dd; 2016-11-20" or ms "1494751821472".

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Right Sizing Recommendations

Get right-sizing recommendations for an Ocean cluster.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Instance Types Filters Simulation

Returns all instances types that match the given filters. These instance types will be used if the cluster is configured with these filters.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
required
object (InstanceTypesFilters)

List of filters. The Instance types that match with all filters compose the Ocean's whitelist parameter. Cannot be configured together with whitelist/blacklist.

architectures
Array of strings
Items Enum: "i386" "x86_64" "arm64"

The filtered instance types will support at least one of the architectures from this list.

categories
Array of strings
Items Enum: "Accelerated_computing" "Compute_optimized" "General_purpose" "Memory_optimized" "Storage_optimized"

The filtered instance types will belong to one of the categories types from this list.

diskTypes
Array of strings
Items Enum: "NVMe" "EBS" "SSD" "HDD"

The filtered instance types will have one of the disk type from this list.

excludeFamilies
Array of strings

Types belonging to a family from the ExcludeFamilies will not be available for scaling (asterisk wildcard is also supported). For example, C* will exclude instance types from these families: c5, c4, c4a, etc.

excludeMetal
boolean
Default: false

In case excludeMetal is set to true, metal types will not be available for scaling.

hypervisor
Array of strings
Items Enum: "nitro" "xen"

The filtered instance types will have a hypervisor type from this list.

includeFamilies
Array of strings

Types belonging to a family from the IncludeFamilies will be available for scaling (asterisk wildcard is also supported). For example, C* will include instance types from these families: c5, c4, c4a, etc.

isEnaSupported
boolean

Ena is supported or not.

maxGpu
integer >= 1

Maximum total number of GPUs.

maxMemoryGiB
number <double> >= 0

Maximum amount of Memory (GiB).

maxNetworkPerformance
integer >= 1

Maximum Bandwidth in Gib/s of network performance.

maxVcpu
integer >= 1

Maximum number of vCPUs available.

minEnis
integer >= 0

Minimum number of network interfaces (ENIs).

minGpu
integer >= 0

Minimum total number of GPUs.

minMemoryGiB
number <double> >= 0

Minimum amount of Memory (GiB).

minNetworkPerformance
integer >= 0

Minimum Bandwidth in Gib/s of network performance.

minVcpu
integer >= 0

Minimum number of vCPUs available.

rootDeviceTypes
Array of strings
Items Enum: "ebs" "instance-store"

The filtered instance types will have a root device types from this list.

virtualizationTypes
Array of strings
Items Enum: "hvm" "paravirtual"

The filtered instance types will support at least one of the virtualization types from this list.

Responses

Request samples

Content type
application/json
{
  • "filters": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Allowed Instance Types

Return the list of the allowed Ocean cluster instance types.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Upgrade Elastigroup to Ocean

Upgrade an Elastigroup with ECS integration into Ocean for ECS cluster.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

groupId
required
string
Example: groupId=sig-1234abcd

The identifier of the Elastigroup to upgrade.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Initiate Roll

Roll an entire Ocean cluster or roll subsets of the cluster by specifying launchSpecIds or instanceIds. Performing this request will start the roll immediately according to defined batches. Note that the first response for a successful request will indicate the start of a roll. In order to check the status of a roll, you can use the GET Roll API using the roll identifier.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
One of
object
batchMinHealthyPercentage
integer
Default: 50

Indicates the threshold of minimum healthy instances in single batch. If the amount of healthy instances in single batch is under the threshold, the cluster roll will fail. If exists, the parameter value will be in range of 1-100. In case of null as value, the default value in the backend will be 50%. Value of param should represent the number in percentage (%) of the batch.

batchSizePercentage
integer

Value (in percent) to set size of batch in roll. Valid values are 0-100.

comment
string

Add a brief description for the roll. The comment is limited to 256 chars.

Responses

Request samples

Content type
application/json
Example
{
  • "roll": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

List Rolls

List rolls of an Ocean cluster.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Update Roll

Update a roll of an Ocean cluster. Performing the request will stop the next batch in a roll.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

ROLL_ID
required
string
Example: scr-12345abc

Ocean Cluster Roll identifier

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
object

Sets the status of the roll.

status
required
string
Value: "STOPPED"

Set status of a roll. Valid values: "STOPPED"

Responses

Request samples

Content type
application/json
{
  • "roll": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Roll

Get status for roll of an Ocean cluster.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

ROLL_ID
required
string
Example: scr-12345abc

Ocean Cluster Roll identifier

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Cluster Container Instances

Get container instances data of an Ocean cluster.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

instanceId
string
Example: instanceId=i-123

Get a specific container instance ec2 instance id.

launchSpecId
string
Example: launchSpecId=ols-123abc

Ocean cluster Virtual Node Group identifier.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Detach Instances

Detach instances from your Ocean cluster.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
instancesToDetach
required
Array of strings

Array of instance identifiers to be detached.

shouldDecrementTargetCapacity
boolean

Determines whether the Ocean cluster's target capacity should be decremented.

shouldTerminateInstances
boolean

Determines whether the detached EC2 instances should be terminated or not.

Responses

Request samples

Content type
application/json
{
  • "instancesToDetach": [
    ],
  • "shouldTerminateInstances": true,
  • "shouldDecrementTargetCapacity": false
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Create VNG

Create a new Ocean ECS virtual node group in the specified account.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
required
object (oceanClusterLaunchSpec-create)

AWS Cluster Virtual Node Group (VNG).

Array of objects

Add attributes to the cluster.

object
Array of objects (launchSpec-blockDeviceMappings)

Block devices that are exposed to the instance. You can specify virtual devices and EBS volumes. This parameter and rootVolumeSize cannot be in the configuration at the same time. This parameter can be null, but if not null, it must contain at least one block device.

Array of arn (string) or name (string)

The instance profile iamRole object.

imageId
string

Set image identifier. Can be null.

Array of objects (Image object, containing the id of the image used to launch instances.)

An array of image objects.

  • You can configure VNG with either the imageId or images objects, but not both simultaneously.
  • For each architecture type (amd64, arm64) only one AMI is allowed.
  • Valid values: null, or an array with at least one element
object (instanceMetadataOptions)

Ocean instance metadata options object for IMDSv2.

instanceTypes
Array of strings

An array of supported instance types for the VNG.

name
required
string

User given name of the virtual node group.

oceanId
required
string

The Ocean cluster identifier. Required for to create a virtual node group.

preferredSpotTypes
Array of strings

When Ocean scales up instances, it takes your preferred types into consideration while maintaining a variety of machine types running for optimized distribution. Learn More

restrictScaleDown
boolean

When set to True, the VNG container instances will be treated as if all tasks running have the restrict-scale-down label. Therefore, Ocean will not scale down container instances unless they are empty.

object (Ocean Scheduling)

An object used to define scheduled tasks such as a manual headroom update.

securityGroupIds
Array of strings

Set security groups. Each element in array should be a security group identifier.

object

Similar to a strategy for an Ocean cluster, but applying only to a virtual node group.

subnetIds
Array of strings

Set the subnets in the VNG. Each element in the array should be a subnet identifier.

Array of objects

List of kay-value pairs of tags.

userData
string <byte>

Base64-encoded MIME user data to make available to the instances.

Responses

Request samples

Content type
application/json
{
  • "launchSpec": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

List VNGs

Get all the custom VNGs for all Ocean clusters in the specified account.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

oceanId
string
Example: oceanId=o-12345abc

Identifier of the Ocean cluster.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get VNG

Get a specific custom launch configuration for an Ocean cluster in the specified account.

Authorizations:
auth
path Parameters
launchSpecId
required
string

Ocean cluster Virtual Node Group identifier.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Delete VNG

Delete a specified virtual node group in an Ocean cluster.

Authorizations:
auth
path Parameters
launchSpecId
required
string

Ocean cluster Virtual Node Group identifier.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

deleteContainerInstances
boolean
Default: false
Example: deleteContainerInstances=true

When set to "true", all instances belonging to the deleted VNG will be drained, detached, and terminated.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Update VNG

Update a specified virtual node group in an Ocean cluster.

Authorizations:
auth
path Parameters
launchSpecId
required
string

Ocean cluster Virtual Node Group identifier.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

autoApplyTags
boolean
Default: false
Example: autoApplyTags=true

Optionally update resource tags on the fly without performing a roll.

Request Body schema: application/json
required
object (oceanClusterLaunchSpec-update)

AWS Cluster Virtual Node Group (VNG).

Array of objects

Add attributes to the cluster.

object
Array of objects (launchSpec-blockDeviceMappings)

Block devices that are exposed to the instance. You can specify virtual devices and EBS volumes. This parameter and rootVolumeSize cannot be in the configuration at the same time. This parameter can be null, but if not null, it must contain at least one block device.

Array of arn (string) or name (string)

The instance profile iamRole object.

imageId
string

Set image identifier. Can be null.

Array of objects (Image object, containing the id of the image used to launch instances.)

An array of image objects.

  • You can configure VNG with either the imageId or images objects, but not both simultaneously.
  • For each architecture type (amd64, arm64) only one AMI is allowed.
  • Valid values: null, or an array with at least one element
object (instanceMetadataOptions)

Ocean instance metadata options object for IMDSv2.

instanceTypes
Array of strings

An array of supported instance types for the VNG.

name
string

User given name of the virtual node group.

preferredSpotTypes
Array of strings

When Ocean scales up instances, it takes your preferred types into consideration while maintaining a variety of machine types running for optimized distribution. Learn More

restrictScaleDown
boolean

When set to True, the VNG container instances will be treated as if all tasks running have the restrict-scale-down label. Therefore, Ocean will not scale down container instances unless they are empty.

object (Ocean Scheduling)

An object used to define scheduled tasks such as a manual headroom update.

securityGroupIds
Array of strings

Set security groups. Each element in array should be a security group identifier.

object

Similar to a strategy for an Ocean cluster, but applying only to a virtual node group.

subnetIds
Array of strings

Set the subnets in the VNG. Each element in the array should be a subnet identifier.

Array of objects

List of kay-value pairs of tags.

userData
string <byte>

Base64-encoded MIME user data to make available to the instances.

Responses

Request samples

Content type
application/json
{
  • "launchSpec": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Import Fargate To Existing Ocean Cluster

Import a Fargate service into an existing Ocean ECS cluster. Upon Fargate service import, Spot clones the selected Fargate services and runs them with the same VPC & Subnet settings on EC2 spot Instances. Ocean will automatically and seamlessly predict and replace spot instances before they are interrupted, ensuring the uptime of the cluster and providing cost-savings of up to 90% over Fargate-enabled ECS clusters.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
services
Array of strings

List of Fargate services by their names. Must contain at least one service.

simpleNewServiceNames
boolean
Default: false

Flag to align imported service names in the following format: sfm_

Responses

Request samples

Content type
application/json
{
  • "services": [
    ],
  • "simpleNewServiceNames": false
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Fargate Services Discovery

Get existing Fargate services in the ECS cluster.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Fargate Migration Status

Get the status of a Fargate service import.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Import Fargate To New Ocean Cluster

This API copies the configuration from a Fargate service into the corresponding fields of an Ocean object. (This process is commonly referred to as importing.) The API returns an Ocean object that is suitable for use in the Create API to create a new Ocean cluster based on your Fargate configuration. If you are migrating a Fargate service that has tags, you must run the Opt In procedure on your Amazon account or IAM role. This is required in order to obtain the necessary Amazon Resource Name (ARN) and resource identifier format for your ECS tasks, container instances, and services. For more information about the required ARN and the Opt In procedure, see the following pages:

The API requires one of the following permissions to be defined in Spot -

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
ecsClusterName
required
string

Name of the cluster in ECS.

keyPair
string

Specify a key pair to attach to the services.

oceanClusterName
required
string

Name of the cluster in new Ocean object.

region
required
string

Name of the AWS region the ECS cluster is in.

services
required
Array of strings[ items ]

Name of the ECS Fargate service to be imported.

Array of objects

Set tags for the service. Items should be unique.

Responses

Request samples

Content type
application/json
{
  • "oceanClusterName": "fargate-import-ocean",
  • "ecsClusterName": "fargateTestCluster",
  • "region": "us-west-1",
  • "services": [
    ],
  • "keyPair": "spot-prod",
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Ecs Cluster Aggregated Detailed Costs

Provides Ecs cluster resource usage and costs over a time interval which can be grouped and/or filtered by AWS tags,
for example - application name (webapp, backend), environment (production, staging), version etc.
The response will contain a breakdown of the cluster resource costs($) in terms of compute (CPU, memory), storage (block, file, rootVolume). The response will group the cluster usage costs based on the preselected default of Ecs Group Type which is composed of Service, Headroom, Custom Object, Idle and Standalone, or user selected AWS tags.
Within the default grouping, costs are broken down for the Service group, and for tag grouping the costs will be broken up by tag value.

Time Rounding Down: The CostAnalysis API applies rounding down to the hours provided during the call.
For example, the value 1707004799099 (In GMT) representing Saturday, February 3, 2024, 23:59:59.099 is rounded down to Saturday, February 3, 2024, 23:00:00.000, resulting in the omission of one hour of cost.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
endTime
required
string

End date value using either the date format "yyyy-MM-dd'T'HH:mm:ss'Z'" or ms "1494751821472".

object

Describe how to filter the costs. Optional field. Can only be used if grouping by tags.

groupBy
string

The parameter we want to group the costs by, default is grouping by ECS group types. Only a tag key can be passed in.

startTime
required
string

Beginning date value using either the date format "yyyy-MM-dd'T'HH:mm:ss'Z'" or ms "1494751821472".

Responses

Request samples

Content type
application/json
{
  • "startTime": 1675209600000,
  • "endTime": 1675216800000,
  • "groupBy": "env",
  • "filter": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Cluster Costs

Describes ECS cluster costs in a time range.
The response will provide the distribution of the costs per cluster.

Deprecated API: This API is no longer supported. As an alternative you may use the "Get Ecs Cluster Aggregated Detailed Costs" API.

Authorizations:
auth
path Parameters
clusterName
required
string
Example: ocean.ecs

The name of the ECS cluster, as set in the Ocean cluster configuration under the "clusterName" field.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

fromDate
required
string

Beginning date value using either the date format "yyyy-mm-dd; 2016-11-20" or ms "1494751821472".

region
required
string
Example: region=us-east-1

Region name.

toDate
required
string

End date value using either the date format "yyyy-mm-dd; 2016-11-20" or ms "1494751821472".

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Launch Container Instances In VNG

Launch container instances in virtual node group.

Authorizations:
auth
path Parameters
launchSpecId
required
string

Ocean cluster Virtual Node Group identifier.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
required
object (Ocean ECS VNG Launch Request)
amount
required
integer

The number of container instances to launch.

Responses

Request samples

Content type
application/json
{
  • "launchRequest": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Ocean GKE

Ocean - Serverless containers for Google Kubernetes Engine

Ocean Concepts and Tutorials

Get Heartbeat Status

Get the heartbeat status of the Ocean Controller for the cluster.
The response returns the heartbeat status and the last heartbeat timestamp.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Create Cluster

Prerequisites:

The Ocean Controller is used to monitor the cluster resources and report back to Ocean.| To install the Ocean Controller, complete and run the following script on a machine with the kubectl command line tool installed and configured:

  #!/usr/bin/env bash
  curl -fsSL http://spotinst-public.s3.amazonaws.com/integrations/kubernetes/cluster-controller/scripts/init.sh | \
  SPOTINST_TOKEN=<ENTER YOUR TOKEN HERE> \
  SPOTINST_ACCOUNT=<ENTER YOUR SPOTINST ACCOUNT ID HERE> \
  SPOTINST_CLUSTER_IDENTIFIER=<ENTER YOUR CLUSTER IDENTIFIER HERE> \
  bash

You may need Kubernetes admin privileges for this script to work. To grant yourself admin privileges, run the following command:

  kubectl create clusterrolebinding <clusterName> --clusterrole=cluster-admin --user=<userEmail>

For more information, refer to our controller installation guides. You can install with Helm, Kubectl or Terraform. For more about Ocean and the Ocean Controller, see the documentation here.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
required
object

The specification of the Ocean cluster.

object (auto-scaler)

The Ocean Kubernetes Autoscaler object.

object (auto-update)

The Ocean Kubernetes AutoUpdate object. If set to 'true', Ocean will ensure that your clusters have an up-to-date configuration according to the respective GKE cluster.

object (Capacity Units)

Capacity specifications for the Ocean cluster.

required
object (Ocean Compute)
controllerClusterId
required
string

Enter the Ocean cluster identifier.

object

Use existing GKE cluster.

name
required
string

Add a name for the Ocean cluster.

object (Ocean GKE Scheduling)

Schedule an action such as a planned shutdown or a cluster roll.

object (Security)
object (Ocean Strategy)

Responses

Request samples

Content type
application/json
{
  • "cluster": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

List Clusters

List the configurations for all Ocean clusters in the specified account.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Delete Cluster

Delete a specified Ocean cluster.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Cluster

Get the configuration for a specified Ocean cluster.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Update Cluster

All Ocean parameters are updatable, excluding the Name and controllerClusterId.
This API supports partial updates, so specific fields can be updated separately.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
required
object

The specification of the Ocean cluster.

object (auto-scaler)

The Ocean Kubernetes Autoscaler object.

object (auto-update)

The Ocean Kubernetes AutoUpdate object. If set to 'true', Ocean will ensure that your clusters have an up-to-date configuration according to the respective GKE cluster.

object (Capacity Units)

Capacity specifications for the Ocean cluster.

object (Ocean Compute)
name
string

Add a name for the Ocean cluster.

object (Ocean GKE Scheduling)

Schedule an action such as a planned shutdown or a cluster roll.

object (Security)
object (Ocean Strategy)

Responses

Request samples

Content type
application/json
{
  • "cluster": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Reimport Cluster

Reimport the cluster's configuration from GKE.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Detach Instances

Detach instances from your Ocean cluster.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
drainingTimeout
integer

(Applies only if shouldTerminateInstances is on) The draining timeout (in seconds) before terminating the instance.

instancesToDetach
required
Array of strings

Array of instance identifiers to be detached.

shouldDecrementTargetCapacity
boolean

Determines whether the Ocean cluster's target capacity should be decremented. (Default false)

shouldTerminateInstances
boolean

Determines whether the detached instances should be terminated or not. (Default true)

Responses

Request samples

Content type
application/json
{
  • "instancesToDetach": [
    ],
  • "shouldTerminateInstances": true,
  • "shouldDecrementTargetCapacity": false,
  • "drainingTimeout": 0
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Elastilog

Get group’s Elastilog by

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

fromDate
required
string

Beginning date value using either the date format "yyyy-mm-dd; 2016-11-20" or ms "1494751821472".

limit
integer <= 1000
Default: 500
Example: limit=200

Maximum number of lines to extract in a response.

resourceId
string
Example: resourceId=i-12345678

Filter extracted log entries for a specific resource identifier. Default: Null

severity
string
Default: "ALL"
Enum: "ALL" "INFO" "DEBUG" "ERROR" "WARN"
Example: severity=INFO

Severity of log entries to extract.

toDate
required
string

End date value using either the date format "yyyy-mm-dd; 2016-11-20" or ms "1494751821472".

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Right Sizing Recommendations

Get right-sizing recommendations for an Ocean cluster and filter them according to namespace or label.

Authorizations:
auth
path Parameters
oceanId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
object

Optional - may be null.

object

Optional - may be null.

namespaces
Array of strings

Optional - may be null. If exists - should contain at least 1 item.

Responses

Request samples

Content type
application/json
{
  • "filter": {
    }
}

Response samples

Content type
application/json
{
  • "response": {
    }
}

Get Cluster Aggregated Detailed Costs

Provides Kubernetes cluster resource usage and costs over a time interval which can be grouped and/or filtered by label/annotaion.
For example - application name (webapp, backend), environment (production, staging), version etc.
The response will contain a breakdown of the cluster resource costs($) in terms of compute (CPU, memory) and storage. The response will group the cluster usage costs based on preselected default of application namespace or user selected label or annotation.
Within the group, resource costs are broken down per resource kind (Deployment, DaemonSet etc.).

Time Rounding Down: The CostAnalysis API applies rounding down to the hours provided during the call.
For example, the value 1707004799099 (In GMT) representing Saturday, February 3, 2024, 23:59:59.099 is rounded down to Saturday, February 3, 2024, 23:00:00.000, resulting in the omission of one hour of cost.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
endTime
required
string

End date value using either the date format "yyyy-MM-dd'T'HH:mm:ss'Z'" or ms "1494751821472".

object

Describe how to filter the costs. Optional field.

groupBy
string
Default: "namespace"
Enum: "namespace" "namespace.label.${labelKey}" "resource.label.${labelKey}" "resource.annotation.${annotationKey}" "namespace.annotation.${annotationKey}"

The parameter we want to group the costs by.

startTime
required
string

Beginning date value using either the date format "yyyy-MM-dd'T'HH:mm:ss'Z'" or ms "1494751821472".

Responses

Request samples

Content type
application/json
{
  • "startTime": "2018-06-20T11:35:02.745Z",
  • "endTime": "2018-06-22T11:30:01.745Z",
  • "groupBy": "namespace.label.env",
  • "filter": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Cluster Aggregated Summary Costs

Provides Kubernetes cluster summary usage and costs over a time interval which can be grouped and/or filtered by label/annotaion,
for example - application name (webapp, backend), environment (production, staging), version etc.
The response will contain a breakdown of the cluster resource costs($) in terms of compute (CPU, memory), storage (block, file, rootVolume). The response will group the cluster usage costs based on preselected default of application namespace or user selected label or annotation.

Time Rounding Down: The CostAnalysis API applies rounding down to the hours provided during the call.
For example, the value 1707004799099 (In GMT) representing Saturday, February 3, 2024, 23:59:59.099 is rounded down to Saturday, February 3, 2024, 23:00:00.000, resulting in the omission of one hour of cost.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
endTime
required
string

End date value using either the date format "yyyy-MM-dd'T'HH:mm:ss'Z'" or ms "1494751821472".

object

Describe how to filter the costs. Optional field.

groupBy
string
Default: "namespace"
Enum: "namespace" "namespace.label.${labelKey}" "resource.label.${labelKey}" "resource.annotation.${annotationKey}" "namespace.annotation.${annotationKey}"

The parameter we want to group the costs by.

startTime
required
string

Beginning date value using either the date format "yyyy-MM-dd'T'HH:mm:ss'Z'" or ms "1494751821472".

Responses

Request samples

Content type
application/json
{
  • "startTime": "2023-07-20T11:35:01.745Z",
  • "endTime": "2023-07-22T11:30:01.745Z",
  • "groupBy": "namespace.label.env",
  • "filter": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Instance Types Filters Simulation

Returns all instances types that match the given filters. These instance types will be used if the cluster is configured with these filters.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
required
object (InstanceTypesFilters)

List of filters. The Instance types that match with all filters compose the Ocean's whitelist parameter. Cannot be configured together with whitelist/blacklist.

excludeFamilies
Array of strings

Types belonging to a family from the ExcludeFamilies will not be available for scaling (asterisk wildcard is also supported).

includeFamilies
Array of strings

Types belonging to a family from the IncludeFamilies will be available for scaling (asterisk wildcard is also supported).

maxMemoryGiB
number <double> >= 0

Maximum amount of Memory (GiB).

maxVcpu
integer >= 1

Maximum number of vcpus available.

minMemoryGiB
number <double> >= 0

Minimum amount of Memory (GiB).

minVcpu
integer >= 0

Minimum number of vcpus available.

Responses

Request samples

Content type
application/json
{
  • "filters": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Create VNG

Create a Virtual Node Group.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

initialNodes
integer
Default: null
Example: initialNodes=1

When set to an integer greater than 0, a corresponding number of nodes will be launched from the virtual node group created.

Request Body schema: application/json
required
object (oceanClusterLaunchSpecCreate)

Ocean Cluster Virtual Node Group (VNG).

object

Object specifying the automatic scaling of an Ocean VNG.

availabilityZones
Array of strings

An array holding availability zones, this configures the availability zones the Ocean may launch instances in per VNG. Can be null.

object (InstanceTypesFilters)

List of filters. The Instance types that match with all filters compose the Ocean's whitelist parameter. Cannot be configured together with whitelist/blacklist.

instanceTypes
Array of strings

An array of supported machine types for the virtual node group. Can be null.

Array of objects

An array of labels to add to the virtual node group. Only custom user labels are allowed, and not Kubernetes built-in labels or Spot internal labels.

required
Array of objects

Add metadata to the cluster.

name
string

Set the name for the virtual node group.

Array of objects

Settings for network interfaces

oceanId
required
string

The Ocean cluster identifier. Required to create the virtual node group.

preferredTypes
Array of strings (preferredTypes)

When Ocean scales up VMs, it prioritizes the preferred instance types for launching new nodes. If launching nodes from this preferred list is not feasible, Ocean will then proceed to utilize the configured instance types available within the cluster. Note that the preferred types must be a subset of the instance types configured for the cluster/vng.

object
restrictScaleDown
boolean

When set to True, VNG nodes will be treated as if all pods running have the restrict-scale-down label. Therefore, Ocean will not scale nodes down unless they are empty.

rootVolumeSizeInGb
integer

Set root volume size (in GB).

rootVolumeType
string
Enum: "pd-standard" "pd-ssd" "pd-balanced"

Set the root volume disk type.

object (Ocean Scheduling)

An object used to define scheduled tasks such as a manual headroom update.

serviceAccount
string

The account used by applications running on the VM to call GCP APIs.

object (shielded-instance-config)

The Ocean shielded instance configuration object.

sourceImage
required
string

Set the image URL. Can be null.

object (storage)

The Ocean virtual node group storage object.

object (strategy)

The Ocean virtual node group strategy object.

tags
Array of strings

Every node launched from this VNG will have those tags. If the value is null, the nodes will have the tags configured at the cluster level.

Array of objects

Add taints to the virtual node group.

Responses

Request samples

Content type
application/json
{
  • "launchSpec": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

List VNGs

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

oceanId
required
string
Example: oceanId=o-12345abc

Identifier of the Ocean cluster.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Import GKE Node Pool To VNG

Returns an Ocean Virtual Node Group (VNG) configuration based on a given GCP GKE Cluster Node Pool.
The returned value ("Imported VNG") can then be used as input to the Create VNG API in order to create an actual VNG in your Ocean cluster.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

nodePoolName
required
string
Example: nodePoolName=test

Name of the Node Pool.

oceanId
required
string
Example: oceanId=o-12345abc

Identifier of the Ocean cluster.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Delete VNG

Delete a specified virtual node group in an Ocean cluster.

Authorizations:
auth
path Parameters
launchSpecId
required
string

Ocean cluster Virtual Node Group identifier.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

deleteNodes
boolean
Default: false
Example: deleteNodes=true

When set to "true", all instances belonging to the deleted Virtual Node Group will be drained, detached, and terminated.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Update VNG

All Ocean parameters in a virtual node group are updatable.

Authorizations:
auth
path Parameters
launchSpecId
required
string

Ocean cluster Virtual Node Group identifier.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
object

Object specifying the automatic scaling of an Ocean VNG.

availabilityZones
Array of strings

An array holding availability zones, this configures the availability zones the Ocean may launch instances in per VNG. Can be null.

object (InstanceTypesFilters)

List of filters. The Instance types that match with all filters compose the Ocean's whitelist parameter. Cannot be configured together with whitelist/blacklist.

instanceTypes
Array of strings

An array of supported machine types for the virtual node group. Can be null.

Array of objects

An array of labels to add to the virtual node group. Only custom user labels are allowed, and not Kubernetes built-in labels or Spot internal labels.

Array of objects

Add metadata to the cluster.

name
string

Set the name for the virtual node group.

oceanId
required
string

The Ocean cluster identifier. Required to create the virtual node group.

preferredTypes
Array of strings (preferredTypes)

When Ocean scales up VMs, it prioritizes the preferred instance types for launching new nodes. If launching nodes from this preferred list is not feasible, Ocean will then proceed to utilize the configured instance types available within the cluster. Note that the preferred types must be a subset of the instance types configured for the cluster/vng.

object
restrictScaleDown
boolean

When set to True, VNG nodes will be treated as if all pods running have the restrict-scale-down label. Therefore, Ocean will not scale nodes down unless they are empty.

rootVolumeSizeInGb
integer

Set root volume size (in GB).

rootVolumeType
string
Enum: "pd-standard" "pd-ssd" "pd-balanced"

Set the root volume disk type.

object (Ocean Scheduling)

An object used to define scheduled tasks such as a manual headroom update.

serviceAccount
string

The account used by applications running on the VM to call GCP APIs.

object (shielded-instance-config)

The Ocean shielded instance configuration object.

sourceImage
required
string

Set the image URL. Can be null.

object (storage)

The Ocean virtual node group storage object.

object (strategy)

The Ocean virtual node group strategy object.

tags
Array of strings

Every node launched from this VNG will have those tags. If the value is null, the nodes will have the tags configured at the cluster level.

Array of objects

Add taints to the virtual node group.

Responses

Request samples

Content type
application/json
{
  • "oceanId": "o-1fff54ed",
  • "name": "lp_name",
  • "sourceImage": "https://www.googleapis.com/compute/v1/projects/gke-node-images/global/images/container-v1-3-v20160517",
  • "serviceAccount": "265168459660-compute@developer.gserviceaccount.com",
  • "rootVolumeSizeInGb": 8,
  • "rootVolumeType": "pd-standard",
  • "metadata": [
    ],
  • "instanceTypes": [
    ],
  • "filters": {
    },
  • "preferredTypes": [
    ],
  • "availabilityZones": [
    ],
  • "tags": [
    ],
  • "taints": [
    ],
  • "labels": [
    ],
  • "autoScale": {
    },
  • "resourceLimits": {
    },
  • "restrictScaleDown": false,
  • "shieldedInstanceConfig": {
    },
  • "strategy": {
    },
  • "storage": {
    },
  • "scheduling": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get VNG

Authorizations:
auth
path Parameters
launchSpecId
required
string

Ocean cluster Virtual Node Group identifier.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Initiate Roll

Roll an entire Ocean cluster or roll subsets of the cluster by specifying launchSpecIds or instanceNames. Performing this request will start the roll immediately, and the roll will take place according to defined batches.

Note that the first response for a successful request will notify about the start of a roll. In order to check the status of a roll, you can use the GET Cluster Roll API using the roll identifier.

Authorizations:
auth
path Parameters
oceanId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
One of
object
batchMinHealthyPercentage
integer
Default: 50

Indicates the threshold percentage of minimum healthy instances in a single batch. If the number is below the threshold, the cluster roll will fail. The parameter value has a range of 1-100 (default = 50%).

batchSizePercentage
integer

Value is a percentage to set the size of a batch in a roll. Valid values are 0-100.

comment
string

Add a comment description for the roll. The comment is limited to 256 chars.

respectPdb
boolean
Default: false

During the roll, if the parameter is set to 'true', PDB is honored during the instance replacement.

Responses

Request samples

Content type
application/json
Example
{
  • "roll": {
    }
}

Response samples

Content type
application/json
{
  • "rollId": "roll-1234",
  • "oceanId": "o-12e31234",
  • "scope": "Cluster",
  • "status": "IN_PROGRESS",
  • "batchNumber": 1,
  • "numOfBatches": 5,
  • "comment": "This is why I deployed my cluster.",
  • "respectPdb": true,
  • "progress": {
    },
  • "instanceNames": [
    ],
  • "launchSpecIds": [
    ],
  • "batchMinHealthyPercentage": 100,
  • "createdAt": "2019-03-24T15:46:09.000Z",
  • "updatedAt": "2019-03-24T15:46:09.000Z"
}

List Rolls

Get status for all rolls of an Ocean cluster.

Authorizations:
auth
path Parameters
oceanId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "status": {
    },
  • "kind": "spotinst:ocean:aws:k8s:cluster:roll",
  • "items": [
    ]
}

Update Roll

Update a roll of an Ocean cluster.

Performing the request will stop the next batch in a roll.

Authorizations:
auth
path Parameters
oceanId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

rollId
required
string
Example: scr-12345abc

Ocean Cluster Roll identifier

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
object

Object that specifies the parameters of a roll (also called a deployment).

status
required
string
Value: "STOPPED"

Set status of a roll. Valid values: "STOPPED"

Responses

Request samples

Content type
application/json
{
  • "roll": {
    }
}

Response samples

Content type
application/json
{
  • "rollId": "roll-1234",
  • "status": "STOPPED",
  • "batchNumber": 1,
  • "numOfBatches": 5,
  • "scope": "Cluster",
  • "progress": {
    },
  • "batchMinHealthyPercentage": 100,
  • "oceanId": "o-12e31234",
  • "respectPdb": true,
  • "createdAt": "2019-03-24T15:46:09.000Z",
  • "updatedAt": "2019-03-24T15:46:09.000Z"
}

Get Roll

Get status for roll of an Ocean cluster.

Authorizations:
auth
path Parameters
oceanId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

rollId
required
string
Example: scr-12345abc

Ocean Cluster Roll identifier

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "rollId": "roll-1234",
  • "oceanId": "o-12e31234",
  • "scope": "Cluster",
  • "status": "IN_PROGRESS",
  • "batchNumber": 1,
  • "numOfBatches": 5,
  • "comment": "This is why I deployed my cluster.",
  • "respectPdb": true,
  • "progress": {
    },
  • "instanceNames": [
    ],
  • "launchSpecIds": [
    ],
  • "batchMinHealthyPercentage": 100,
  • "createdAt": "2019-03-24T15:46:09.000Z",
  • "updatedAt": "2019-03-24T15:46:09.000Z"
}

Get Cluster Nodes

Get nodes data of an Ocean cluster.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

instanceName
string
Example: instanceName=sin-123

Get a specific node by instance name.

launchSpecId
string
Example: launchSpecId=ols-123abc

Ocean cluster Virtual Node Group identifier.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Upgrade Elastigroup To Ocean

Prerequisites | Perform the following validations prior to upgrade executions: | * Group identifier cannot be null. * Group identifier exists in Elastigroup. * Group should be a GKE Elastigroup with defined scaling policy. * Group identifier is already managed by Ocean.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

groupId
required
string

Elastigroup identifier

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Import GKE Cluster To Ocean

Returns an Ocean Cluster configuration, and optionally Virtual Node Group (VNG) configurations based on a given GKE Cluster and its Node Pools.
The returned values ("Imported Cluster/VNGs") can then be used as inputs to the Create Cluster/VNG APIs in order to create the respectful resources.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

clusterName
required
string
Example: clusterName=test-gke

Name of the GKE Cluster.

includeLaunchSpecs
boolean
Default: true
Example: includeLaunchSpecs=true

When set to "true", GKE cluster node pools will be imported to Ocean custom VNG ("customLaunchSpec") configurations.

location
required
string
Example: location=us-central1-a

Location GKE Cluster Master.

nodePoolName
string
Example: nodePoolName=test

Name of the Node Pool to use as a default for the Cluster configuration.

Request Body schema: application/json
required
object

The specification of the Ocean cluster.

object (auto-scaler)

The Ocean Kubernetes Autoscaler object.

availabilityZones
Array of strings

An array holding availability zones, this configures the availability zones the Ocean may launch instances in per VNG. Can be null.

Array of objects
object (Capacity Units)

Capacity specifications for the Ocean cluster.

controllerClusterId
string

Enter the Ocean cluster identifier.

object

The type of instances that may or may not be a part of the Ocean cluster.

name
string

Add a name for the Ocean cluster.

Responses

Request samples

Content type
application/json
{
  • "cluster": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Launch Nodes In VNG

Launch nodes in virtual node group.

Authorizations:
auth
path Parameters
launchSpecId
required
string

Ocean cluster Virtual Node Group identifier.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
object (Ocean GKE Virtual Node Group Launch Request)
amount
required
integer

The number of nodes to launch.

Responses

Request samples

Content type
application/json
{
  • "launchRequest": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Ocean AKS

Ocean - Serverless containers for Azure Kubernetes Service

Ocean Concepts and Tutorials

Create Cluster

Creates an Ocean entity according to a given specification.

Notes:

It is recommended to import all necessary information from the existing AKS cluster using the Ocean AKS Cluster Import API call and use its output to create a fully configured Ocean cluster.

The Ocean Controller is used to monitor the cluster resources and report back to Ocean SaaS. A properly functioning controller is mandatory for Ocean to operate.

Installing the controller can be easily done by Helm, Terraform or a script using the guide.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
required
object (ocean-cluster-2)

The Ocean cluster.

required
object (Ocean AKS - AKS Cluster Configuration)

AKS cluster configuration. Cannot be updated.

object (Ocean AKS Autoscaler)

The Ocean Kubernetes Autoscaler object.

controllerClusterId
required
string

Enter a unique Ocean cluster identifier. Cannot be updated.

object (Ocean AKS Health)

The Ocean AKS Health object.

object (Ocean AKS Logging)

The Ocean AKS Logging object.

name
required
string

Add a name for the Ocean cluster.

object (Ocean AKS Scheduling)

An object used to specify times when the cluster will turn off. Once the shutdown time will be over, the cluster will return to its previous state.

required
object (Ocean AKS Virtual Node Group Template)

Responses

Request samples

Content type
application/json
{
  • "cluster": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

List Clusters

List the configurations for all Ocean clusters in the specified account.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Cluster

Get the configurations for a specified Ocean cluster.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Update Cluster

Update a specified Ocean cluster.
This API supports partial updates, so specific fields can be updated separately.

Notes:
When labels, tags and taints are updated in the VNG template, all existing nodes from VNGs that inherit these properties from the tamplate will be updated as well.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
required
object (ocean-cluster-3)

The Ocean cluster.

object (Ocean AKS Autoscaler)

The Ocean Kubernetes Autoscaler object.

object (Ocean AKS Health)

The Ocean AKS Health object.

object (Ocean AKS Logging)

The Ocean AKS Logging object.

name
string

A name for the Ocean cluster.

object (Ocean AKS Scheduling)

An object used to specify times when the cluster will turn off. Once the shutdown time will be over, the cluster will return to its previous state.

object (Ocean AKS Virtual Node Group Template)

Responses

Request samples

Content type
application/json
{
  • "cluster": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Delete Cluster

Delete a specified Ocean cluster.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Import Cluster

The Import Cluster API call returns a JSON formatted Ocean cluster specification for a given AKS cluster and import identifier. The returned specification is ready to use in the Ocean AKS Cluster Create API call.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

aksClusterName
required
string
Example: aksClusterName=test-cluster

The name of the aks cluster.

resourceGroupName
required
string
Example: resourceGroupName=test-clust_group

The name of the resource group of the AKS cluster.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Launch New Nodes

Launch new nodes for a cluster.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
adjustment
required
integer >= 1

The number of nodes to launch.

applicableVmSizes
Array of strings >= 1
availabilityZones
Array of strings

An Array holding Availability Zones, this configures the availability zones the Ocean may launch instances in per VNG.

minCoresPerNode
integer >= 2

Minimum number of core per node.

minMemoryGiBPerNode
number <float> >= 2

Minimum memory per node.

oceanId
required
string

Ocean cluster identifier.

preferredLifecycle
string
Enum: "Spot" "Regular"

The preferred life cycle to launch the node. If not specified, the life cycle is chosen accoring to the scaled VNG.

vngIds
Array of strings >= 1

Responses

Request samples

Content type
application/json
{
  • "oceanId": "o-134abcd",
  • "vngIds": [
    ],
  • "preferredLifecycle": "Spot",
  • "availabilityZones": [
    ],
  • "adjustment": 2,
  • "minCoresPerNode": 2,
  • "minMemoryGiBPerNode": 2,
  • "applicableVmSizes": [
    ]
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Detach Nodes

Detach Nodes nodes for a cluster.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
nodeNamesToDetach
required
Array of strings >= 1

Node names to detach from the Ocean cluster.

oceanId
required
string

Ocean cluster identifier.

Responses

Request samples

Content type
application/json
{
  • "oceanId": "o-134abcd",
  • "nodeNamesToDetach": [
    ]
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Create Virtual Node Group

Create a virtual node group.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
required
object (Ocean AKS Virtual Node Group)
object (Ocean AKS Auto Scale)

Object specifying the automatic scaling of an Ocean VNG.

availabilityZones
Array of strings

An Array holding Availability Zones, this configures the availability zones the Ocean may launch nodes in per VNG.
Select zone 0 if you have a workload that requires no availability zone redundancy (AZ=null). You can select this option either alone or together with other availability zones.
In case zone 0 is selected together with other availability zones, nodes of zone 0 will be scaled only for workloads that demand it.

labels
object

key-value pairs of labels to add to the virtual node group.
Only custom user labels are allowed, and not Kubernetes built-in labels or Spot internal labels.
The following are not allowed:

  • "kubernetes.azure.com/agentpool"
  • "kubernetes.io/arch"* "kubernetes.io/os"
  • "node.kubernetes.io/instance-type"
  • "topology.kubernetes.io/region"
  • "topology.kubernetes.io/zone"
  • "kubernetes.azure.com/cluster"
  • "kubernetes.azure.com/mode"
  • "kubernetes.azure.com/role"
  • "kubernetes.azure.com/scalesetpriority"
  • "kubernetes.io/hostname"
  • "kubernetes.azure.com/storageprofile"
  • "kubernetes.azure.com/storagetier"
  • "kubernetes.azure.com/instance-sku"
  • "kubernetes.azure.com/node-image-version"
  • "kubernetes.azure.com/subnet"
  • "kubernetes.azure.com/vnet"
  • "kubernetes.azure.com/ppg"
  • "kubernetes.azure.com/encrypted-set"
  • "kubernetes.azure.com/accelerator"
  • "kubernetes.azure.com/fips_enabled"
  • "kubernetes.azure.com/os-sku"
name
required
string

Enter a name for the virtual node group.

object (Ocean AKS Node Count Limits)

Limit the number of nodes in a VNG.

object (Ocean AKS Node Pool Properties)

The Ocean Node Pool Properties.

oceanId
required
string

Ocean cluster identifier.

object (Ocean VNG AKS Scheduling)

An object used to specify times when the virtual node group will turn off all its node pools. Once the shutdown time will be over, the virtual node group will return to its previous state.

object (Ocean AKS Strategy)

The Ocean AKS Strategy object.

tags
object

A maximum of 20 unique key-value pairs for VM tags in the virtual node group. Note: Azure has a tag limit of 50 per node pool.

Array of objects

Add taints to a virtual node group.

object (Ocean AKS VM Sizes)

The Ocean AKS VM Sizes object.

Responses

Request samples

Content type
application/json
{
  • "virtualNodeGroup": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

List Virtual Node Groups

List the configurations for all virtual node groups in the account or in a specified cluster.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

oceanId
required
string
Example: oceanId=o-12345abc

Identifier of the Ocean cluster.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Virtual Node Group

Get the configuration of a specified virtual node group.

Authorizations:
auth
path Parameters
virtualNodeGroupId
required
string
Example: vng-12345abc

Ocean Virtual Node Group identifier.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Update Virtual Node Group

Update a specified virtual node group in an Ocean cluster.
This API supports partial updates, so specific fields can be updated separately.

Notes:
When labels, tags and taints are updated the existing nodes are updated as well.

Authorizations:
auth
path Parameters
virtualNodeGroupId
required
string
Example: vng-12345abc

Ocean Virtual Node Group identifier.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
required
object (Ocean AKS Virtual Node Group)
object (Ocean AKS Auto Scale)

Object specifying the automatic scaling of an Ocean VNG.

availabilityZones
Array of strings

An Array holding Availability Zones, this configures the availability zones the Ocean may launch instances in per VNG.

labels
object

key-value pairs of labels to add to the virtual node group.
Only custom user labels are allowed, and not Kubernetes built-in labels or Spot internal labels.
The following are not allowed:

  • "kubernetes.azure.com/agentpool"
  • "kubernetes.io/arch"* "kubernetes.io/os"
  • "node.kubernetes.io/instance-type"
  • "topology.kubernetes.io/region"
  • "topology.kubernetes.io/zone"
  • "kubernetes.azure.com/cluster"
  • "kubernetes.azure.com/mode"
  • "kubernetes.azure.com/role"
  • "kubernetes.azure.com/scalesetpriority"
  • "kubernetes.io/hostname"
  • "kubernetes.azure.com/storageprofile"
  • "kubernetes.azure.com/storagetier"
  • "kubernetes.azure.com/instance-sku"
  • "kubernetes.azure.com/node-image-version"
  • "kubernetes.azure.com/subnet"
  • "kubernetes.azure.com/vnet"
  • "kubernetes.azure.com/ppg"
  • "kubernetes.azure.com/encrypted-set"
  • "kubernetes.azure.com/accelerator"
  • "kubernetes.azure.com/fips_enabled"
  • "kubernetes.azure.com/os-sku"
name
string

Enter a name for the virtual node group.

object (Ocean AKS Node Count Limits)

Limit the number of nodes in a VNG.

object (Ocean AKS Node Pool Properties)

The Ocean Node Pool Properties.

object (Ocean VNG AKS Scheduling)

An object used to specify times when the virtual node group will turn off all its node pools. Once the shutdown time will be over, the virtual node group will return to its previous state.

object (Ocean AKS Strategy)

The Ocean AKS Strategy object.

tags
object

A maximum of 20 unique key-value pairs for VM tags in the virtual node group. Note: Azure has a tag limit of 50 per node pool.

Array of objects

Add taints to a virtual node group.

object (Ocean AKS VM Sizes)

The Ocean AKS VM Sizes object.

Responses

Request samples

Content type
application/json
{
  • "virtualNodeGroup": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Delete Virtual Node Group

Delete a specified virtual node group in an Ocean cluster.

Authorizations:
auth
path Parameters
virtualNodeGroupId
required
string
Example: vng-12345abc

Ocean Virtual Node Group identifier.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

deleteNodes
boolean
Default: false
Example: deleteNodes=true

When set to "true", all instances belonging to the deleted Virtual Node Group will be drained, detached, and terminated.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Import Virtual Node Group

The Import Ocean Virtual Node Group (VNG) returns a JSON formatted Ocean Virtual Node Group specification based on a given AKS Node Pool. The returned specification is ready to use in the Ocean AKS Virtual Node Group Create API call.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

nodePoolName
required
string
Example: nodePoolName=nodePoolNameTest

The name of the Node Pool.

oceanId
required
string
Example: oceanId=o-12345abc

Identifier of the Ocean cluster.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Virtual Node Group Allowed VM Sizes

Get the allowed VM sizes that can be launched according to the virtual node group properties and selected VM size filters.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

virtualNodeGroupId
required
string
Example: virtualNodeGroupId=vng-12345abc

Ocean Virtual Node Group identifier.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Initiate Roll

Roll an entire Ocean cluster or roll subsets of the cluster by specifying vngIds, nodePoolNames or nodeNames. Performing this request will start the roll immediately and run it in defined batches. Note that the first response for a successful request will indicate the start of a roll. In order to check the status of a roll, you can use the GET Roll API.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
One of
batchMinHealthyPercentage
integer
Default: 50

Indicates the threshold of minimum healthy nodes in single batch. If the amount of healthy nodes in single batch is under the threshold, the roll will fail. If exists, the parameter value will be in range of 1-100. In case of null as value, the default value in the backend will be 50%. Value of param should represent the number in percentage (%) of the batch.

batchSizePercentage
integer

Value as a percent to set the size of a batch in a roll. Valid values are 0-100. In case of null as value, the default value in the backend will be 20%.

comment
string

Add a comment description for the roll. The comment is limited to 256 chars and optional.

respectPdb
boolean
Default: true

During the roll, if the parameter is set to true we honor PDB during the nodes replacement.

respectRestrictScaleDown
boolean
Default: false

During the roll, if the parameter is set to true we honor Restrict Scale Down label during the nodes replacement.

Responses

Request samples

Content type
application/json
Example
{
  • "batchSizePercentage": 25,
  • "comment": "This is why I deployed my cluster.",
  • "respectPdb": false,
  • "respectRestrictScaleDown": true,
  • "batchMinHealthyPercentage": 100
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

List Rolls

Get status for all rolls of an Ocean cluster.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Roll

Get status for a roll of an Ocean cluster.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

rollId
required
string
Example: acr-12345abc

Ocean cluster roll identifier.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Stop Roll

Stop a roll of an Ocean cluster.

Performing the request will stop the next batch in a roll.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

rollId
required
string
Example: acr-12345abc

Ocean cluster roll identifier.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Migration Discovery

Get information about nodes which can be migrated into Ocean.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

shouldFetchPods
boolean
Example: shouldFetchPods=true

Should fetch data about running pods for each node.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Create Migration

Migrate to ocean workloads that run on unmanaged nodes by specifying nodePoolNames or nodeNames. Performing this request will start the migration immediately and run it in defined batches. Note that the first response for a successful request will indicate the start of a migration. In order to check the status of a migration, you can use the GET migration API.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
One of
batchMinHealthyPercentage
integer [ 1 .. 100 ]
Default: 50

Indicates the threshold of minimum healthy nodes in single batch. If the amount of healthy nodes in single batch is under the threshold, the migration will fail. If exists, the parameter value will be in range of 1-100. In case of null as value, the default value in the backend will be 50%. Value of param should represent the number in percentage (%) of the batch.

batchSizePercentage
integer [ 1 .. 100 ]

Value as a percent to set the size of a batch in a migration. Valid values are 0-100. In case of null as value, the default value in the backend will be 20%.

comment
string

Add a comment description for the migration. The comment is limited to 256 chars and optional.

nodeNames
Array of strings

List of node names to be migrated. Each identifier is a string. nodeNames can be null, and cannot be used together with nodePoolNames.

respectPdb
boolean
Default: true

During the migration, if the parameter is set to true we honor PDB during the nodes replacement.

respectRestrictScaleDown
boolean
Default: false

During the migration, if the parameter is set to true we honor Restrict Scale Down label during the nodes replacement.

shouldEvictStandalonePods
boolean
Default: true

If the parameter is set to true we will evict all standalone pods during the migration.

shouldTerminateNodes
boolean
Default: true

If the parameter is set to true we will terminate the node after the migration has finished successfully. If the parameter is set to false we will leave the nodes. example: true

Responses

Request samples

Content type
application/json
Example
{
  • "batchSizePercentage": 25,
  • "comment": "This is why I deployed my cluster.",
  • "respectPdb": false,
  • "respectRestrictScaleDown": true,
  • "shouldTerminateNodes": true,
  • "shouldEvictStandalonePods": true,
  • "batchMinHealthyPercentage": 100,
  • "nodeNames": [
    ]
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

List Migrations

Get status for all migrations of an Ocean cluster.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Migration

Get status for a migration of an Ocean cluster.

Authorizations:
auth
path Parameters
migrationId
required
string
Example: scr-12345abc

Ocean cluster workload migration identifier.

oceanClusterId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Stop Migration

Stop a migration of an Ocean cluster.

Performing the request will stop the next batch in a migration.

Authorizations:
auth
path Parameters
migrationId
required
string
Example: scr-12345abc

Ocean cluster workload migration identifier.

oceanClusterId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Fetch Right Sizing Recommendations

Get right-sizing recommendations for an Ocean cluster and filter them according to namespace or label.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
object

Optional - may be null.

object

Optional - may be null.

namespaces
Array of strings

Optional - may be null. If exists - should contain at least 1 item.

Responses

Request samples

Content type
application/json
{
  • "filter": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Fetch Elastilogs

Fetch the log of an Ocean cluster.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-12345abc

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

fromDate
required
string

Beginning date value using either the date format "yyyy-mm-dd; 2016-11-20" or ms "1494751821472".

limit
integer <= 1000
Default: 500
Example: limit=200

Maximum number of lines to extract in a response.

resourceId
string
Example: resourceId=i-12345678

Filter extracted log entries for a specific resource identifier. Default: Null

severity
string
Default: "ALL"
Enum: "ALL" "INFO" "DEBUG" "ERROR" "WARN"
Example: severity=INFO

Severity of log entries to extract.

toDate
required
string

End date value using either the date format "yyyy-mm-dd; 2016-11-20" or ms "1494751821472".

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Initiate Auto upgrade

Update the Ocean AKS cluster's VNGs with the latest version of the control plane's version after upgrading by specifying the scope. Performing this request will update the VNGs with a new version if available and run a cluster roll if set. If the response is successful, the old and new versions will be included in the response along with the updated VNGs. If a cluster roll is set in the request, the first response for a successful request will indicate the start of a roll. In order to check the status of the roll, you can use the GET Roll API.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

aksClusterName
required
string
Example: aksClusterName=test-cluster

The name of the aks cluster.

resourceGroupName
required
string
Example: resourceGroupName=test-clust_group

The name of the resource group of the AKS cluster.

Request Body schema: application/json
required
object (Upgrade Config)

The Configuration for scheduling automatic upgrades of your cluster to ensure it stays updated with the latest version.

applyRoll
boolean

When set to True, a cluster roll will be initiated if a new version is available to upgrade in the dedicated virtual node groups.

object

The parameters of the cluster roll that will be initiated.

scopeVersion
string
Value: "patch"

The scope of the upgrade version.

Responses

Request samples

Content type
application/json
{
  • "upgradeConfig": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Cluster Aggregated Detailed Costs

Provides Kubernetes cluster resource usage and costs over a time interval which can be grouped and/or filtered by label/annotaion,
for example - application name (webapp, backend), environment (production, staging), version etc.
The response will contain a breakdown of the cluster resource costs($) in terms of compute (CPU, memory) and storage. The response will group the cluster usage costs based on preselected default of application namespace or user selected label or annotation.
Within the group, resource costs are broken down per resource kind (Deployment, DaemonSet etc.).

Time Rounding Down: The CostAnalysis API applies rounding down to the hours provided during the call.
For example, the value 1707004799099 (In GMT) representing Saturday, February 3, 2024, 23:59:59.099 is rounded down to Saturday, February 3, 2024, 23:00:00.000, resulting in the omission of one hour of cost.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
endTime
required
string

End date value using either the date format "yyyy-MM-dd'T'HH:mm:ss'Z'" or ms "1494751821472".

object

Describe how to filter the costs. Optional field.

groupBy
string
Default: "namespace"
Enum: "namespace" "namespace.label.${labelKey}" "resource.label.${labelKey}" "resource.annotation.${annotationKey}" "namespace.annotation.${annotationKey}"

The parameter we want to group the costs by.

startTime
required
string

Beginning date value using either the date format "yyyy-MM-dd'T'HH:mm:ss'Z'" or ms "1494751821472".

Responses

Request samples

Content type
application/json
{
  • "startTime": "2023-07-20T11:35:01.745Z",
  • "endTime": "2023-07-22T11:30:01.745Z",
  • "groupBy": "namespace.label.env",
  • "filter": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Cluster Aggregated Summary Costs

Provides Kubernetes cluster summary usage and costs over a time interval which can be grouped and/or filtered by label/annotaion,
for example - application name (webapp, backend), environment (production, staging), version etc.
The response will contain a breakdown of the cluster resource costs($) in terms of compute (CPU, memory), storage (block, file, rootVolume). The response will group the cluster usage costs based on preselected default of application namespace or user selected label or annotation.

Time Rounding Down: The CostAnalysis API applies rounding down to the hours provided during the call.
For example, the value 1707004799099 (In GMT) representing Saturday, February 3, 2024, 23:59:59.099 is rounded down to Saturday, February 3, 2024, 23:00:00.000, resulting in the omission of one hour of cost.

Authorizations:
auth
path Parameters
oceanClusterId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
endTime
required
string

End date value using either the date format "yyyy-MM-dd'T'HH:mm:ss'Z'" or ms "1494751821472".

object

Describe how to filter the costs. Optional field.

groupBy
string
Default: "namespace"
Enum: "namespace" "namespace.label.${labelKey}" "resource.label.${labelKey}" "resource.annotation.${annotationKey}" "namespace.annotation.${annotationKey}"

The parameter we want to group the costs by.

startTime
required
string

Beginning date value using either the date format "yyyy-MM-dd'T'HH:mm:ss'Z'" or ms "1494751821472".

Responses

Request samples

Content type
application/json
{
  • "startTime": "2023-07-20T11:35:01.745Z",
  • "endTime": "2023-07-22T11:30:01.745Z",
  • "groupBy": "namespace.label.env",
  • "filter": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Ocean Insights

Insights allows Spot users on AWS to connect a Kubernetes cluster and within minutes get the cluster analyzed with insights about the current state of infrastructure in the cluster, and the potential effect of migrating the specific cluster into Ocean. Through its powerful features, Ocean presents significant opportunities for infrastructure optimization and automation, which are on display in the Insights console. Connected to Kubernetes clusters and running a continuous analysis, Ocean Insights delivers a holistic picture of your cluster and workloads behavior, from expected cloud costs and resource utilization. Through a simple UI, users will see a breakdown of potential savings when they first connect to Ocean Insights.

Ocean Insights

Create Cluster

Creates an Ocean Insight entity according to a given specification.

Prerequisite:

The Ocean Controller is used to monitor the cluster resources and report back to Ocean. The Ocean Controller is required for Ocean Insights.

To install the Ocean Controller, complete and run the following script on a machine with the kubectl command line tool installed and configured:

#!/usr/bin/env bash
curl -fsSL http://spotinst-public.s3.amazonaws.com/integrations/kubernetes/cluster-controller/scripts/init.sh | \
SPOTINST_TOKEN=<ENTER YOUR TOKEN HERE> \
SPOTINST_ACCOUNT=<ENTER YOUR SPOTINST ACCOUNT ID HERE> \
SPOTINST_CLUSTER_IDENTIFIER=<ENTER YOUR CLUSTER IDENTIFIER HERE> \
bash
Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
required
object (Ocean Insight)
controllerClusterId
required
string

The reporting identifier for the Ocean Controller.

name
required
string

Add a name for the Ocean Insight cluster.

Responses

Request samples

Content type
application/json
{
  • "cluster": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

List Clusters

Get the configurations for all Ocean Insights clusters in the specified account.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Cluster

Get the configurations for a specified Ocean Insight cluster.

Authorizations:
auth
path Parameters
OCEAN_INSIGHT_ID
required
string
Example: oic-abcd1234

The ID of the Ocean Insight cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Delete Cluster

Delete a specified Ocean Insight cluster.

Authorizations:
auth
path Parameters
OCEAN_INSIGHT_ID
required
string
Example: oic-abcd1234

The ID of the Ocean Insight cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Ocean CD

Ocean CD is a fully managed continuous delivery ('CD') solution for Kubernetes applications. Designed for end-to-end automation and verification of frequent application-deployment processes at scale. Ocean CD architecture and API enable a simple and secured installation that seamlessly fits into any Kubernetes environment. Users get key features like granular visibility, SaaS logic that manage the rollout process, verifications of the applied workloads and automatic rollbacks. To enable Ocean CD, install the controller with one simple command in the Kubernetes cluster and create the following entities using the API:

  • Strategy
  • Rollout Spec
Ocean CD

List Ocean CD Clusters

List all Ocean CD clusters.

Authorizations:
auth

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Ocean CD Cluster

Get an existing Ocean CD cluster.

Authorizations:
auth
path Parameters
clusterId
required
string
Example: cluster-prod

The identifier of the Ocean CD cluster

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Create Ocean CD Verification Provider

Create Ocean CD Verification Provider. Only one provider type can be defined

Authorizations:
auth
Request Body schema: application/json
required
object (oceanCDVerificationProvider)
object (Ocean CD Verification Provider CloudWatch)
clusterIds
required
Array of strings

List of cluster IDs that this Verification Provider will be applied to

object (Ocean CD Verification Provider Datadog)
object (Ocean CD Verification Provider Jenkins)
name
required
string

Identifier name for Ocean CD Verification Provider. Must be unique

object (Ocean CD Verification Provider NewRelic)
object (Ocean CD Verification Provider Prometheus)

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

List Ocean CD Verification Providers

List all Ocean CD Verification Providers.

Authorizations:
auth

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Ocean CD Verification Provider

Get an existing Ocean CD Verification Provider.

Authorizations:
auth
path Parameters
name
required
string
Example: datadog-prod

The identifier of the Ocean CD Verification Provider

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Update Ocean CD Verification Provider

Full Update of Ocean CD Verification Provider configuration. All non included fields will be nullified

Authorizations:
auth
path Parameters
name
required
string
Example: datadog-prod

The identifier name of the Ocean CD Verification Provider

Request Body schema: application/json
required
object (oceanCDVerificationProviderUpdate)
object (Ocean CD Verification Provider CloudWatch)
clusterIds
required
Array of strings

List of cluster ids that this Verification Provider will be applied to

object (Ocean CD Verification Provider Datadog)
object (Ocean CD Verification Provider Jenkins)
object (Ocean CD Verification Provider NewRelic)
object (Ocean CD Verification Provider Prometheus)

Responses

Request samples

Content type
application/json
{}

Patch Ocean CD Verification Provider

Partial update Ocean CD Verification Provider configuration.

Authorizations:
auth
path Parameters
name
required
string
Example: datadog-prod

The identifier name of the Ocean CD Verification Provider

Request Body schema: application/json
required
object (Ocean CD Verification Provider)

Ocean CD Verification Provider spec entity.

object (Ocean CD Verification Provider CloudWatch)
clusterIds
Array of strings

List of cluster ids that this Verification Provider will be applied to

object (Ocean CD Verification Provider Datadog)
object (Ocean CD Verification Provider Jenkins)
object (Ocean CD Verification Provider NewRelic)
object (Ocean CD Verification Provider Prometheus)

Responses

Request samples

Content type
application/json
{}

Delete Ocean CD Verification Provider

Delete an existing Ocean CD Verification Provider.

Authorizations:
auth
path Parameters
name
required
string
Example: datadog-prod

The identifier name of the Ocean CD Verification Provider

Responses

Create Ocean CD Verification Template

Create Ocean CD Verification Template.

Authorizations:
auth
Request Body schema: application/json
required
object (oceanCDVerificationTemplate)

The object specifying a set of metrics that need to be analyzed during the rollout, and the values that are considered successful or failed

Array of objects (Ocean CD Verification Template argument)

List of verification arguments. You may specify either value OR valueFrom but not both. In case args:value is already defined in the RolloutSpec entity, there is no need to also specify it in the VerificationTemplate entity

required
Array of objects (Ocean CD Verification Metric)

List of verification metrics

name
required
string

Identifier name for Ocean CD Verification Template. Must be a unique name

Responses

Request samples

Content type
application/json
{
  • "verificationTemplate": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

List Ocean CD Verification Templates

List all Ocean CD Verification Templates.

Authorizations:
auth

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Ocean CD Verification Template

Get an existing Ocean CD Verification Template.

Authorizations:
auth
path Parameters
name
required
string
Example: latency-validation

The identifier of the Ocean CD Verification Template

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Update Ocean CD Verification Template

Full update of Ocean CD Verification Template configuration. All non included fields will be nullified

Authorizations:
auth
path Parameters
name
required
string
Example: latency-validation

The identifier name of the Ocean CD Verification Template

Request Body schema: application/json
required
object (oceanCDVerificationTemplateUpdate)
Array of objects (Ocean CD Verification Template argument)

List of verification arguments

required
Array of objects (Ocean CD Verification Metric)

List of verification metrics

Responses

Request samples

Content type
application/json
{
  • "verificationTemplate": {
    }
}

Patch Ocean CD Verification Template

Partial update Ocean CD Verification Template configuration.

Authorizations:
auth
path Parameters
name
required
string
Example: latency-validation

The identifier name of the Ocean CD Verification Template

Request Body schema: application/json
required
object (Ocean CD Verification Template)

Ocean CD Verification Template spec entity.

Array of objects (Ocean CD Verification Template argument)

List of verification arguments

required
Array of objects (Ocean CD Verification Metric)

List of verification metrics

Responses

Request samples

Content type
application/json
{
  • "verificationTemplate": {
    }
}

Delete Ocean CD Verification Template

Delete an existing Ocean CD Verification Template.

Authorizations:
auth
path Parameters
name
required
string
Example: latency-validation

The identifier name of the Ocean CD Verification Template

Responses

Create Ocean CD Strategy

Create Ocean CD Strategy.

Authorizations:
auth
Request Body schema: application/json
required
object (Ocean CD Strategy)

Ocean CD strategy. Use in RolloutSpec to decide what strategy to use when applying SpotDeployment

object (Ocean CD Strategy Canary)

Represents Canary strategy

name
required
string

Identifier name for Ocean CD Strategy. Must be unique

object (Ocean CD Strategy Rolling Update)

Represents Rolling Update strategy

Responses

Request samples

Content type
application/json
{
  • "strategy": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

List Ocean CD Strategies

List all Ocean CD strategies.

Authorizations:
auth

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Ocean CD Strategy

Get an existing Ocean CD Strategy.

Authorizations:
auth
path Parameters
strategyName
required
string
Example: canary-prod

The identifier name of the Ocean CD Strategy

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Update Ocean CD Strategy

Full update of Ocean CD strategy configuration. All non included fields will be nullified

Authorizations:
auth
path Parameters
strategyName
required
string
Example: canary-prod

The identifier name of the Ocean CD Strategy

Request Body schema: application/json
required
object (Ocean CD Strategy)

Ocean CD strategy. Use in RolloutSpec to decide what strategy to use when applying SpotDeployment

object (Ocean CD Strategy Canary)

Represents Canary strategy

object (Ocean CD Strategy Rolling Update)

Represents Rolling Update strategy

Responses

Request samples

Content type
application/json
{
  • "strategy": {
    }
}

Patch Ocean CD Strategy

Partial update of Ocean CD strategy configuration.

Authorizations:
auth
path Parameters
strategyName
required
string
Example: canary-prod

The identifier name of the Ocean CD Strategy

Request Body schema: application/json
required
object (Ocean CD Strategy)

Ocean CD strategy. Use in RolloutSpec to decide what strategy to use when applying SpotDeployment

object (Ocean CD Strategy Canary)

Represents Canary strategy

object (Ocean CD Strategy Rolling Update)

Represents Rolling Update strategy

Responses

Request samples

Content type
application/json
{
  • "strategy": {
    }
}

Delete Ocean CD Strategy

Delete an existing Ocean CD strategy.

Authorizations:
auth
path Parameters
strategyName
required
string
Example: canary-prod

The identifier name of the Ocean CD Strategy

Responses

Create Ocean CD Rollout Spec

Create Ocean CD Rollout Spec.

Authorizations:
auth
Request Body schema: application/json
required
object (Ocean CD Rollout Spec)

Ocean CD Rollout Spec entity.

object (Ocean CD Rollout Spec Failure Policy)

Holds information on how to react when failure happens

name
required
string

The identifier name for Ocean CD Rollout Spec. Must be unique

object (Ocean CD Spot Deployment Selector)

Represents the SpotDeployment selector

Array of objects (Ocean CD Spot Deployment Selector)

You must specify either spotDeployment OR spotDeployments but not both. Every SpotDeployment has to be unique. If more than one SpotDeployment has been configured, no traffic managers can be set as part of the RolloutSpec. For such case ensure that each of the chosen SpotDeployments are being exposed with different Kubernetes services

required
object (Ocean CD Rollout Spec Strategy)

Determines the Ocean CD strategy

object (Ocean CD Rollout Spec Traffic)

Hosts all of the supported service meshes needed to enable more fine-grained traffic routing. In case SpotDeployments contains more than one SpotDeployment the traffic manager may not be configured

Responses

Request samples

Content type
application/json
{
  • "rolloutSpec": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

List Ocean CD Rollout Specs

List all Ocean CD Rollout Specs.

Authorizations:
auth

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Ocean CD Rollout Spec

Get the configuration of an existing Ocean CD Rollout Spec.

Authorizations:
auth
path Parameters
rolloutSpecName
required
string
Example: app-rolloutspec

The identifier name of the Ocean CD Rollout Spec

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Update Ocean CD Rollout Spec

Full update Ocean CD Rollout Spec configuration. All non included fields will be nullified

Authorizations:
auth
path Parameters
rolloutSpecName
required
string
Example: app-rolloutspec

The identifier name of the Ocean CD Rollout Spec

Request Body schema: application/json
required
object (Ocean CD Rollout Spec)

Ocean CD rollout spec entity

object (Ocean CD Rollout Spec Failure Policy)

Holds information on how to react when failure happens

object (Ocean CD Spot Deployment Selector)

Represents the SpotDeployment selector

Array of objects (Ocean CD Spot Deployment Selector)

You must specify either SpotDeployment OR SpotDeployments but not both. Every SpotDeployment has to be unique. If more than one SpotDeployment has been configured, no traffic managers can be set as part of the RolloutSpec. For such case ensure that each of the chosen SpotDeployments are being exposed with different Kubernetes services

required
object (Ocean CD Rollout Spec Strategy)

Determines the Ocean CD strategy

object (Ocean CD Rollout Spec Traffic)

Hosts all of the supported service meshes needed to enable more fine-grained traffic routing. In case SpotDeployments contains more than one SpotDeployment the traffic manager may not be configured

Responses

Request samples

Content type
application/json
{
  • "rolloutSpec": {
    }
}

Patch Ocean CD Rollout Spec

Partial update Ocean CD Rollout Spec configuration.

Authorizations:
auth
path Parameters
rolloutSpecName
required
string
Example: app-rolloutspec

The identifier name of the Ocean CD Rollout Spec

Request Body schema: application/json
required
object (Ocean CD Rollout Spec)

Ocean CD rollout spec entity

object (Ocean CD Rollout Spec Failure Policy)

Holds information on how to react when failure happens

object (Ocean CD Spot Deployment Selector)

Represents the SpotDeployment selector

Array of objects (Ocean CD Spot Deployment Selector)

You must specify either SpotDeployment OR SpotDeployments but not both. Every SpotDeployment has to be unique. If more than one SpotDeployment has been configured, no traffic managers can be set as part of the RolloutSpec. For such case ensure that each of the chosen SpotDeployments are being exposed with different Kubernetes services

required
object (Ocean CD Rollout Spec Strategy)

Determines the Ocean CD strategy

object (Ocean CD Rollout Spec Traffic)

Hosts all of the supported service meshes needed to enable more fine-grained traffic routing. In case SpotDeployments contains more than one SpotDeployment the traffic manager may not be configured

Responses

Request samples

Content type
application/json
{
  • "rolloutSpec": {
    }
}

Delete Ocean CD Rollout Spec

Delete an existing Ocean CD Rollout Spec.

Authorizations:
auth
path Parameters
rolloutSpecName
required
string
Example: app-rolloutspec

The identifier name of the Ocean CD Rollout Spec

Responses

Get Ocean CD Rollout by ID

Get Ocean CD rollout by ID.

Authorizations:
auth
path Parameters
rolloutId
required
string
Example: rol-123456

The identifier name of the Ocean CD rollout

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Ocean CD Rollout Actions

Execute action on an existing Ocean CD rollout.

Authorizations:
auth
path Parameters
rolloutId
required
string
Example: rol-123456

The identifier name of the Ocean CD rollout

Request Body schema: application/json
action
required
string
Enum: "promote" "promoteFull" "pause" "abort" "retry"

An action that might be applied to a rollout

Responses

Request samples

Content type
application/json
{
  • "action": "promote"
}

List Ocean CD Rollouts

List Ocean CD rollouts.

Authorizations:
auth
query Parameters
fromDate
required
string
Example: fromDate=1656622800000

The timestamp indicating the starting point from which only rollouts initiated thereafter will be listed

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Ocean CD Rollout Status

Get Ocean CD rollout status.

Authorizations:
auth
path Parameters
rolloutId
required
string
Example: rol-1234567890

The identifier name of the Ocean CD rollout

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Ocean CD Latest Rollouts

Get Ocean CD latest rollout(s).

Authorizations:
auth
query Parameters
clusterId
required
string
Example: clusterId=cluster-id

The identifier name of Ocean CD cluster

count
required
string
Example: count=1

Number of intended responses, sorted from the last one down

namespace
required
string
Example: namespace=namespace-name

The Kubernetes namespace in which the rollout is running

spotDeployment
required
string
Example: spotDeployment=spotDeployment-name

The identifier name of the associated SpotDeployment

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Ocean CD Ongoing Rollouts Number

Get Ocean CD ongoing rollouts number.

Authorizations:
auth

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Ocean CD Rollout Verification

Get Ocean CD rollout verification.

Authorizations:
auth
path Parameters
rolloutId
required
string
Example: rol-123456

The identifier name of the Ocean CD Rollout Verification

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Ocean CD Rollout Definition

Get Ocean CD rollout definition.

Authorizations:
auth
path Parameters
rolloutId
required
string
Example: rol-123456

The identifier name of the Ocean CD rollout

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Ocean CD Rollout Resource

Get Ocean CD rollout resource.

Authorizations:
auth
path Parameters
rolloutId
required
string
Example: rol-123456

The identifier name of the Ocean CD rollout

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Ocean CD Rollout Phase

Get Ocean CD rollout phase.

Authorizations:
auth
path Parameters
rolloutId
required
string
Example: rol-123456

The identifier name of the Ocean CD rollout

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Ocean CD Rollout Strategy Override

Get Ocean CD rollout Strategy override entity.

Authorizations:
auth
path Parameters
rolloutId
required
string
Example: rol-123456

The identifier of the Ocean CD Rollout

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

List Ocean CD Workloads

List all Ocean CD workloads.

Authorizations:
auth

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Ocean CD Workload's Active Operation

Get the ongoing operation being applied to the workload.

Authorizations:
auth
path Parameters
namespace
required
string
Example: oceancd

The Kubernetes namespace within which the workload exists

workloadName
required
string
Example: app

The name of the workload

query Parameters
clusterId
required
string
Example: clusterId=prod-cluster

The identifier name of Ocean CD cluster within which the workload exists

kind
required
string
Example: kind=SpotDeployment

The workload's Kubernetes kind. Currently only the SpotDeployment kind is supported

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Ocean CD Workload's Revision

Get Ocean CD Workload's revision.

Authorizations:
auth
path Parameters
namespace
required
string
Example: oceancd

The Kubernetes namespace within which the workload exists

workloadName
required
string
Example: app

The name of the workload

query Parameters
clusterId
required
string
Example: clusterId=prod-cluster

The identifier name of Ocean CD cluster within which the workload exists

kind
required
string
Example: kind=SpotDeployment

The workload's Kubernetes kind. Currently only the SpotDeployment kind is supported

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Ocean CD Restart Workload

Restart Ocean CD workload.

Authorizations:
auth
path Parameters
namespace
required
string
Example: oceancd

The Kubernetes namespace within which the workload exists

workloadName
required
string
Example: app

The name of the workload

query Parameters
clusterId
required
string
Example: clusterId=prod-cluster

The identifier name of Ocean CD cluster within which the workload exists

kind
required
string
Example: kind=SpotDeployment

The workload's Kubernetes kind. Currently only the SpotDeployment kind is supported

Responses

Ocean CD Retry Workload

Retry Ocean CD workload.

Authorizations:
auth
path Parameters
namespace
required
string
Example: oceancd

The Kubernetes namespace within which the workload exists

revisionId
required
string

The associated revision ID

workloadName
required
string
Example: app

The name of the workload

query Parameters
clusterId
required
string
Example: clusterId=prod-cluster

The identifier name of Ocean CD cluster within which the workload exists

kind
required
string
Example: kind=SpotDeployment

The workload's Kubernetes kind. Currently only the SpotDeployment kind is supported

Responses

Ocean CD Rollback Workload

Rollback Ocean CD workload.

Authorizations:
auth
path Parameters
namespace
required
string
Example: oceancd

The Kubernetes namespace within which the workload exists

revisionId
required
string

The associated revision ID

workloadName
required
string
Example: app

The name of the workload

query Parameters
clusterId
required
string
Example: clusterId=prod-cluster

The identifier name of Ocean CD cluster within which the workload exists

kind
required
string
Example: kind=SpotDeployment

The workload's Kubernetes kind. Currently only the SpotDeployment kind is supported

Responses

Get Ocean CD Workload Graph

Get Ocean CD workload graph.

Authorizations:
auth
path Parameters
namespace
required
string
Example: oceancd

The Kubernetes namespace within which the workload exists

workloadName
required
string
Example: app

The name of the workload

query Parameters
clusterId
required
string
Example: clusterId=prod-cluster

The identifier name of Ocean CD cluster within which the workload exists

kind
required
string
Example: kind=SpotDeployment

The workload's Kubernetes kind. Currently only the SpotDeployment kind is supported

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Ocean Spark

Ocean for Apache Spark is a managed cloud-native Spark platform that can be deployed in your cloud account.

Running on top of Ocean, Spot’s serverless infrastructure engine for containers, Ocean Spark makes it easy for your data teams to be successful with Apache Spark on Kubernetes, without dealing with the complexity of managing servers.

Ocean Spark

Create Cluster

Create Ocean Spark Cluster

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
required
object (Ocean Spark Cluster)

The object specifying the configuration of the Ocean Spark cluster.

object (oceanSparkClusterConfig)

The object specifying the configuration of the Ocean Spark cluster.

oceanClusterId
required
string (oceanClusterId)

A unique identifier for the Ocean cluster

Responses

Request samples

Content type
application/json
{
  • "cluster": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

List Clusters

List the Ocean Spark clusters in the specified account.

Authorizations:
auth
query Parameters
accountId
string
Example: accountId=act-123456789

The ID of the account associated with your token. If omitted the oldest account in the organization will be used.

controllerClusterId
string (controllerClusterId)
Example: controllerClusterId=my-ocean-cluster

Optionally filter on the reporting identifier of the Ocean controller in the Ocean cluster (controllerClusterId)

fromDate
string
Example: fromDate=2020-09-01 or fromDate=1598918400000

Get items on or after this date (ISO 8601 or Unix timestamp)

state
any (oceanSparkClusterState)
Enum: "AVAILABLE" "PROGRESSING" "DEGRADED" "FAILING" "UNKNOWN" "UNREACHABLE" "DELETING"
Example: state=AVAILABLE

Optionally filter on the current state of the Ocean Spark cluster

toDate
string
Example: toDate=2020-09-01 or fromDate=1598918400000

Get items on or before this date (ISO 8601 or Unix timestamp)

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Cluster

Describe an Ocean Spark cluster.

Authorizations:
auth
path Parameters
clusterId
required
string (oceanSparkClusterId)
Example: osc-20fac3f1

A unique identifier for the Ocean Spark cluster

query Parameters
accountId
string
Example: accountId=act-123456789

The ID of the account associated with your token. If omitted the oldest account in the organization will be used.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Delete Cluster

Delete an Ocean Spark cluster.

Removing a cluster will disconnect it from Ocean for Spark. This action is permanent and cannot be undone.

The Ocean for Spark resources will be uninstalled from the cluster, but the Ocean cluster itself (and related Kubernetes resources) will not be deleted.

Authorizations:
auth
path Parameters
clusterId
required
string (oceanSparkClusterId)
Example: osc-20fac3f1

A unique identifier for the Ocean Spark cluster

query Parameters
accountId
string
Example: accountId=act-123456789

The ID of the account associated with your token. If omitted the oldest account in the organization will be used.

Responses

Update Cluster

All Ocean Spark configuration parameters are updatable. This API supports partial updates, so specific fields can be updated separately.

Authorizations:
auth
path Parameters
clusterId
required
string (oceanSparkClusterId)
Example: osc-20fac3f1

A unique identifier for the Ocean Spark cluster

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
required
object (Ocean Spark Cluster)

The object specifying the configuration of the Ocean Spark cluster.

required
object (oceanSparkClusterConfig)

The object specifying the configuration of the Ocean Spark cluster.

object (oceanSparkClusterConfigCompute)

The object specifying the Ocean Spark Compute configuration.

object (oceanSparkClusterConfigIngress)

The object specifying the Ocean Spark Ingress configuration.

object (oceanSparkClusterConfigLogCollection)

The object specifying the Ocean Spark Log Collection configuration.

object (oceanSparkClusterConfigSpark)

The object specifying the Ocean Spark Spark configuration.

object (oceanSparkClusterConfigWebhook)

The object specifying the Ocean Spark Webhook configuration.

object (oceanSparkClusterConfigWorkspaces)

The object specifying the Ocean Spark Workspaces configuration.

Responses

Request samples

Content type
application/json
{
  • "cluster": {
    }
}

Cluster Spark Core Hours

Gets the number of core hours applications have consumed.

Authorizations:
auth
query Parameters
accountId
string
Example: accountId=act-123456789

The ID of the account associated with your token. If omitted the oldest account in the organization will be used.

clusterId
Array of strings (oceanSparkClusterId)
Example: clusterId=osc-20fac3f1
period
string <date-time>
Example: period=2021-11

The month to query from.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Cluster application completion trend

Aggregates the number of apps reaching a terminal state (completed, failed, killed, ...) within time buckets.

Authorizations:
auth
path Parameters
clusterId
required
string (oceanSparkClusterId)
Example: osc-20fac3f1

A unique identifier for the Ocean Spark cluster

query Parameters
accountId
string
Example: accountId=act-123456789

The ID of the account associated with your token. If omitted the oldest account in the organization will be used.

since
required
string <date-time>
Example: since=2021-11-22

Date at which to start the analysis. If the time range up to now is less or equal to a day, values are reported grouped per hours. Otherwise, values are reported grouped per days.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Cluster application load history

Reports the number of applications in pending and running state within time buckets.

Authorizations:
auth
path Parameters
clusterId
required
string (oceanSparkClusterId)
Example: osc-20fac3f1

A unique identifier for the Ocean Spark cluster

query Parameters
accountId
string
Example: accountId=act-123456789

The ID of the account associated with your token. If omitted the oldest account in the organization will be used.

since
required
string <date-time>
Example: since=2021-11-22

Date at which to start the analysis. If the time range up to now is less or equal to a day, values are reported grouped per hours. Otherwise, values are reported grouped per days.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Cluster runtime statistics

Returns a summary of the cluster usage since a given date in the past.

Authorizations:
auth
path Parameters
clusterId
required
string (oceanSparkClusterId)
Example: osc-20fac3f1

A unique identifier for the Ocean Spark cluster

query Parameters
accountId
string
Example: accountId=act-123456789

The ID of the account associated with your token. If omitted the oldest account in the organization will be used.

since
required
string <date-time>
Example: since=2021-11-22

Date at which to start the analysis. If the time range up to now is less or equal to a day, values are reported grouped per hours. Otherwise, values are reported grouped per days.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

List Applications

List Spark applications on all Ocean Spark clusters in the specified account. This endpoint is paginated (cursor pagination).

Authorizations:
auth
query Parameters
accountId
string
Example: accountId=act-123456789

The ID of the account associated with your token. If omitted the oldest account in the organization will be used.

after
string (after)
Example: after=MjAyMS0xMS0xOFQwOTo1MjowNS43Mzg4NjArMDA6MDB8NWM3NGY2MDYtZDYxNy00MzcxLWE5ZDktNjc2ZDkxMzRlNWFk

If specified, the page returned in the response contains the items right after this cursor in the ordering

appType
string (oceanSparkApplicationType)
Enum: "batch" "notebook" "spark-connect" "hive-thrift-server" "spark-connect-and-hive-thrift-server"
Example: appType=notebook

Optionally filter on the type of the Spark application

before
string (before)
Example: before=MjAyMS0xMS0xOFQwOTo1MjowNS43Mzg4NjArMDA6MDB8NWM3NGY2MDYtZDYxNy00MzcxLWE5ZDktNjc2ZDkxMzRlNWFk

If specified, the page returned in the response contains the items right before this cursor in the ordering

clusterId
string (oceanSparkClusterId)
Example: clusterId=osc-20fac3f1

Optionally filter on the Ocean Spark cluster ID

jobId
string (oceanSparkJobId) ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a...
Example: jobId=daily-reporting

Optionally filter on the job ID

maxCreatedAt
string <date-time>
Example: maxCreatedAt=2021-11-22T00:00

Optionally filter on the creation date

maxUpdatedAt
string <date-time>
Example: maxUpdatedAt=2021-11-22T00:00

Optionally filter on the last update date

minCreatedAt
string <date-time>
Example: minCreatedAt=2021-11-22T00:00

Optionally filter on the creation date

minUpdatedAt
string <date-time>
Example: minUpdatedAt=2021-11-22T00:00

Optionally filter on the last update date

order
string
Default: "DESC"
Enum: "ASC" "DESC"

The direction of the ordering

orderBy
string
Default: "CREATED_AT"
Enum: "CREATED_AT" "COST_IN_CENTS" "DURATION"

The field on which to sort

pageSize
integer
Default: 20

The number of applications returned by page

searchTerm
string

Optionally search for a substring of the application ID, application display name, job ID or job display name

state
any (oceanSparkApplicationState)
Enum: "PENDING" "RUNNING" "COMPLETED" "COMPLETED_WITH_WARNINGS" "FAILED" "KILLED" "TIMED_OUT"
Example: state=RUNNING

Optionally filter on the state of the Spark application

submissionSource
string (oceanSparkApplicationSubmissionSource)
Enum: "public-api" "jupyter-enterprise-gateway"
Example: submissionSource=public-api

Optionally filter on the submission source of the Spark application

userId
integer (userId)
Example: userId=59438

Optionally filter on the user who created the Spark application

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

List Applications in Cluster

List the Spark applications in a specific cluster. This endpoint is paginated (cursor pagination).

Authorizations:
auth
path Parameters
clusterId
required
string (oceanSparkClusterId)
Example: osc-20fac3f1

A unique identifier for the Ocean Spark cluster

query Parameters
accountId
string
Example: accountId=act-123456789

The ID of the account associated with your token. If omitted the oldest account in the organization will be used.

after
string (after)
Example: after=MjAyMS0xMS0xOFQwOTo1MjowNS43Mzg4NjArMDA6MDB8NWM3NGY2MDYtZDYxNy00MzcxLWE5ZDktNjc2ZDkxMzRlNWFk

If specified, the page returned in the response contains the items right after this cursor in the ordering

appType
string (oceanSparkApplicationType)
Enum: "batch" "notebook" "spark-connect" "hive-thrift-server" "spark-connect-and-hive-thrift-server"
Example: appType=notebook

Optionally filter on the type of the Spark application

before
string (before)
Example: before=MjAyMS0xMS0xOFQwOTo1MjowNS43Mzg4NjArMDA6MDB8NWM3NGY2MDYtZDYxNy00MzcxLWE5ZDktNjc2ZDkxMzRlNWFk

If specified, the page returned in the response contains the items right before this cursor in the ordering

order
string
Default: "DESC"
Enum: "ASC" "DESC"

The direction of the ordering

orderBy
string
Default: "CREATED_AT"
Enum: "CREATED_AT" "COST_IN_CENTS" "DURATION"

The field on which to sort

pageSize
integer
Default: 20

The number of applications returned by page

state
any (oceanSparkApplicationState)
Enum: "PENDING" "RUNNING" "COMPLETED" "COMPLETED_WITH_WARNINGS" "FAILED" "KILLED" "TIMED_OUT"
Example: state=RUNNING

Optionally filter on the state of the Spark application

submissionSource
string (oceanSparkApplicationSubmissionSource)
Enum: "public-api" "jupyter-enterprise-gateway"
Example: submissionSource=public-api

Optionally filter on the submission source of the Spark application

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Submit an Application

Submit a Spark application in an Ocean Spark cluster

Authorizations:
auth
path Parameters
clusterId
required
string (oceanSparkClusterId)
Example: osc-20fac3f1

A unique identifier for the Ocean Spark cluster

query Parameters
accountId
string
Example: accountId=act-123456789

The ID of the account associated with your token. If omitted the oldest account in the organization will be used.

Request Body schema: application/json
appId
string (oceanSparkApplicationId) ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a...

A unique identifier for the Spark application, set by the user or auto-generated from the job ID

object

Configurations for the Spark application supplied in the request. Prefer using a config template for configurations that are stable across runs. Configurations in configOverrides have precedence over those in the config template.

configTemplateId
string (oceanSparkConfigTemplateId) ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a...

A unique identifier for a configuration template, set by the user.

jobId
required
string (oceanSparkJobId) ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a...

The ID of the job to which the Spark application belongs. If a job with this ID does not exist yet, it will be created.

submissionSource
string (oceanSparkApplicationSubmissionSource)
Enum: "public-api" "jupyter-enterprise-gateway"

The source that initiated the application submission

Responses

Request samples

Content type
application/json
{
  • "appId": "daily-reporting-2021-08-18",
  • "jobId": "daily-reporting",
  • "configOverrides": {
    },
  • "configTemplateId": "large-app",
  • "submissionSource": "public-api"
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Application

Describe a Spark application in an Ocean Spark cluster.

Authorizations:
auth
path Parameters
applicationId
required
string (oceanSparkApplicationId) ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a...
Example: daily-reporting-2021-08-18

A unique identifier for the Spark application, set by the user or auto-generated from the job ID

clusterId
required
string (oceanSparkClusterId)
Example: osc-20fac3f1

A unique identifier for the Ocean Spark cluster

query Parameters
accountId
string
Example: accountId=act-123456789

The ID of the account associated with your token. If omitted the oldest account in the organization will be used.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Delete or kill an Application

For pending Spark applications, the creation request is canceled. For running Spark applications, the application is forcibly interrupted.

Authorizations:
auth
path Parameters
applicationId
required
string (oceanSparkApplicationId) ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a...
Example: daily-reporting-2021-08-18

A unique identifier for the Spark application, set by the user or auto-generated from the job ID

clusterId
required
string (oceanSparkClusterId)
Example: osc-20fac3f1

A unique identifier for the Ocean Spark cluster

query Parameters
accountId
string
Example: accountId=act-123456789

The ID of the account associated with your token. If omitted the oldest account in the organization will be used.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

List Application Issues

List the issues associated with the Spark Application.

Authorizations:
auth
path Parameters
applicationId
required
string (oceanSparkApplicationId) ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a...
Example: daily-reporting-2021-08-18

A unique identifier for the Spark application, set by the user or auto-generated from the job ID

clusterId
required
string (oceanSparkClusterId)
Example: osc-20fac3f1

A unique identifier for the Ocean Spark cluster

query Parameters
accountId
string
Example: accountId=act-123456789

The ID of the account associated with your token. If omitted the oldest account in the organization will be used.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Stream Driver log

Stream the driver log of a Spark application in real time.

Authorizations:
auth
path Parameters
applicationId
required
string (oceanSparkApplicationId) ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a...
Example: daily-reporting-2021-08-18

A unique identifier for the Spark application, set by the user or auto-generated from the job ID

clusterId
required
string (oceanSparkClusterId)
Example: osc-20fac3f1

A unique identifier for the Ocean Spark cluster

query Parameters
accountId
string
Example: accountId=act-123456789

The ID of the account associated with your token. If omitted the oldest account in the organization will be used.

Responses

Download Driver log

Download an archive of the driver logs for a finished spark application.

Authorizations:
auth
path Parameters
applicationId
required
string (oceanSparkApplicationId) ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a...
Example: daily-reporting-2021-08-18

A unique identifier for the Spark application, set by the user or auto-generated from the job ID

clusterId
required
string (oceanSparkClusterId)
Example: osc-20fac3f1

A unique identifier for the Ocean Spark cluster

query Parameters
accountId
string
Example: accountId=act-123456789

The ID of the account associated with your token. If omitted the oldest account in the organization will be used.

Responses

Download Executor logs

Download an archive of the executor logs for a finished spark application.

Authorizations:
auth
path Parameters
applicationId
required
string (oceanSparkApplicationId) ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a...
Example: daily-reporting-2021-08-18

A unique identifier for the Spark application, set by the user or auto-generated from the job ID

clusterId
required
string (oceanSparkClusterId)
Example: osc-20fac3f1

A unique identifier for the Ocean Spark cluster

query Parameters
accountId
string
Example: accountId=act-123456789

The ID of the account associated with your token. If omitted the oldest account in the organization will be used.

Responses

Stream Kubernetes events

Stream Kubernetes events about the Spark application in real time.

Authorizations:
auth
path Parameters
applicationId
required
string (oceanSparkApplicationId) ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a...
Example: daily-reporting-2021-08-18

A unique identifier for the Spark application, set by the user or auto-generated from the job ID

clusterId
required
string (oceanSparkClusterId)
Example: osc-20fac3f1

A unique identifier for the Ocean Spark cluster

query Parameters
accountId
string
Example: accountId=act-123456789

The ID of the account associated with your token. If omitted the oldest account in the organization will be used.

Responses

List Config Templates

List config templates across all clusters.

Authorizations:
auth
query Parameters
accountId
string
Example: accountId=act-123456789

The ID of the account associated with your token. If omitted the oldest account in the organization will be used.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

List Config Templates in Cluster

List the config templates tied to a specific cluster.

Authorizations:
auth
path Parameters
clusterId
required
string (oceanSparkClusterId)
Example: osc-20fac3f1

A unique identifier for the Ocean Spark cluster

query Parameters
accountId
string
Example: accountId=act-123456789

The ID of the account associated with your token. If omitted the oldest account in the organization will be used.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Create Config Template

Create a new configuration template

Authorizations:
auth
path Parameters
clusterId
required
string (oceanSparkClusterId)
Example: osc-20fac3f1

A unique identifier for the Ocean Spark cluster

query Parameters
accountId
string
Example: accountId=act-123456789

The ID of the account associated with your token. If omitted the oldest account in the organization will be used.

Request Body schema: application/json
required
object

The piece of configuration contained in the config template.

displayName
string (oceanSparkConfigTemplateDisplayName)

A non-unique free-form name for the config template used in the Spot console. Defaults to the config template ID.

id
required
string (oceanSparkConfigTemplateId) ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a...

A unique identifier for a configuration template, set by the user.

Responses

Request samples

Content type
application/json
{
  • "id": "large-app",
  • "displayName": "Large application",
  • "config": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Config Template

Describe a config template tied to an Ocean Spark cluster.

Authorizations:
auth
path Parameters
clusterId
required
string (oceanSparkClusterId)
Example: osc-20fac3f1

A unique identifier for the Ocean Spark cluster

configTemplateId
required
string (oceanSparkConfigTemplateId) ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a...
Example: large-app

A unique identifier for a configuration template, set by the user.

query Parameters
accountId
string
Example: accountId=act-123456789

The ID of the account associated with your token. If omitted the oldest account in the organization will be used.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Put Config Template

Update a config template by replacing the existing configuration with the one provided in the request body.

Authorizations:
auth
path Parameters
clusterId
required
string (oceanSparkClusterId)
Example: osc-20fac3f1

A unique identifier for the Ocean Spark cluster

configTemplateId
required
string (oceanSparkConfigTemplateId) ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a...
Example: large-app

A unique identifier for a configuration template, set by the user.

query Parameters
accountId
string
Example: accountId=act-123456789

The ID of the account associated with your token. If omitted the oldest account in the organization will be used.

Request Body schema: application/json
object

The piece of configuration that will replace the existing configuration

displayName
string (oceanSparkConfigTemplateDisplayName)

A non-unique free-form name for the config template used in the Spot console. Defaults to the config template ID.

Responses

Request samples

Content type
application/json
{
  • "displayName": "Large application",
  • "config": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Delete Config Template

Delete a config template.

Authorizations:
auth
path Parameters
clusterId
required
string (oceanSparkClusterId)
Example: osc-20fac3f1

A unique identifier for the Ocean Spark cluster

configTemplateId
required
string (oceanSparkConfigTemplateId) ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a...
Example: large-app

A unique identifier for a configuration template, set by the user.

query Parameters
accountId
string
Example: accountId=act-123456789

The ID of the account associated with your token. If omitted the oldest account in the organization will be used.

Responses

List Jobs

List jobs on all Ocean Spark clusters in the specified account.

Authorizations:
auth
query Parameters
accountId
string
Example: accountId=act-123456789

The ID of the account associated with your token. If omitted the oldest account in the organization will be used.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

List Jobs in Cluster

List the Ocean Spark jobs in a specific cluster.

Authorizations:
auth
path Parameters
clusterId
required
string (oceanSparkClusterId)
Example: osc-20fac3f1

A unique identifier for the Ocean Spark cluster

query Parameters
accountId
string
Example: accountId=act-123456789

The ID of the account associated with your token. If omitted the oldest account in the organization will be used.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Job

Describe an Ocean Spark job in an Ocean Spark cluster.

Authorizations:
auth
path Parameters
clusterId
required
string (oceanSparkClusterId)
Example: osc-20fac3f1

A unique identifier for the Ocean Spark cluster

jobId
required
string (oceanSparkJobId) ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a...
Example: daily-reporting

A unique identifier for an Ocean Spark job.

query Parameters
accountId
string
Example: accountId=act-123456789

The ID of the account associated with your token. If omitted the oldest account in the organization will be used.

maxCreatedAt
string <date-time>
Example: maxCreatedAt=2021-11-22T00:00

Optionally filter app history on the creation date. To retrieve the history with the response, you must provide either minCreatedAt or maxCreatedAt.

minCreatedAt
string <date-time>
Example: minCreatedAt=2021-11-22T00:00

Optionally filter app history on the creation date. To retrieve the history with the response, you must provide either minCreatedAt or maxCreatedAt.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Put Job Config Template

Attach or update an attached config template by replacing the existing configuration with the one provided in the request body.

Authorizations:
auth
path Parameters
clusterId
required
string (oceanSparkClusterId)
Example: osc-20fac3f1

A unique identifier for the Ocean Spark cluster

jobId
required
string (oceanSparkJobId) ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a...
Example: daily-reporting

A unique identifier for an Ocean Spark job.

query Parameters
accountId
string
Example: accountId=act-123456789

The ID of the account associated with your token. If omitted the oldest account in the organization will be used.

Request Body schema: application/json
object

The piece of configuration that will replace the existing configuration, if empty then the job configuration will be removed

arguments
Array of strings (Arguments)
availabilityZone
string (Availabilityzone)

The availability zone to use for the Spark application pods. Leave this empty and Ocean Spark will choose the best availability zone for the Spark application

object (Dependencies)

Dependencies of the Spark application

object (DriverSpec)

A configuration for a Spark driver (no required field)

object (ExecutorSpec)

A configuration for a Spark executor (no required field)

object (Hadoopconf)
hadoopConfigMap
string (Hadoopconfigmap)
image
string (Image)
imagePullPolicy
string (Imagepullpolicy)
imagePullSecrets
Array of strings (Imagepullsecrets)
initContainerImage
string (Initcontainerimage)
interactive
boolean (Interactive)
object (Labels)

Labels to be attached to the custom resource of the application.

object (LogCollection)

Configure the application logs collection

mainApplicationFile
string (Mainapplicationfile)
mainClass
string (Mainclass)
memoryOverheadFactor
number (Memoryoverheadfactor)
namespace
string (Namespace)

The Kubernetes namespace the Spark application should run in. The provided namespace must be present in the cluster's Spark app namespace list. If empty, Ocean Spark will use the default 'spark-apps' namespace

priority
string (Priority)

The priority of the Spark application.

pythonVersion
string (PythonVersion)
Default: "3"
Enum: "2" "3"

An enumeration.

serviceAccountName
string (ServiceAccountName)

The Kubernetes service account to assign to the Spark application pods If empty Ocean Spark will use the default spark-driver service account

object (Shuffle)

External Shuffle storage configuration. This is used to configure the external shuffle storage plugin in Spark allowing the shuffle data to be stored on an external storage system. This is useful to handle spot kill more gracefully and allow for executor scaledown when the shuffle data is stored externally.

object (Sparkconf)
sparkConfigMap
string (Sparkconfigmap)
sparkVersion
string (Sparkversion)
Timeout (string) or TimeoutSpec (object) (Timeout)
timeToLiveSeconds
integer (Timetoliveseconds)
type
string (SparkApplicationType)
Enum: "Java" "Python" "Scala"

An enumeration.

Array of objects (Volumes)

Responses

Request samples

Content type
application/json
{
  • "config": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Attach Dedicated Virtual Node Group

Attach an Ocean Virtual Group to the Ocean Spark cluster.

Authorizations:
auth
path Parameters
clusterId
required
string (oceanSparkClusterId)
Example: osc-20fac3f1

A unique identifier for the Ocean Spark cluster

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
required
object (Ocean Spark VNG)

The object specifying the Ocean Spark Dedicated Virtual Node Group.

id
required
string

The Ocean Virtual Node Group Id

Responses

Request samples

Content type
application/json
{
  • "virtualNodeGroup": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Detach Dedicated Virtual Node Group

Detach an Ocean Virtual Group to the Ocean Spark cluster.

Authorizations:
auth
path Parameters
clusterId
required
string (oceanSparkClusterId)
Example: osc-20fac3f1

A unique identifier for the Ocean Spark cluster

query Parameters
accountId
string
Example: accountId=act-123456789

The ID of the account associated with your token. If omitted the oldest account in the organization will be used.

Responses

Create Workspace

Create Ocean Spark Workspace

Authorizations:
auth
path Parameters
clusterId
required
string (oceanSparkClusterId)
Example: osc-20fac3f1

A unique identifier for the Ocean Spark cluster

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
name
string

The name of the workspace.

Responses

Request samples

Content type
application/json
{
  • "name": "cosmos"
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

List Workspaces

List the Ocean Spark workspaces in the specified cluster.

Authorizations:
auth
path Parameters
clusterId
required
string (oceanSparkClusterId)
Example: osc-20fac3f1

A unique identifier for the Ocean Spark cluster

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Workspace

Describe an Ocean Spark workspace.

Authorizations:
auth
path Parameters
clusterId
required
string (oceanSparkClusterId)
Example: osc-20fac3f1

A unique identifier for the Ocean Spark cluster

workspaceId
required
string (oceanSparkWorkspaceId)
Example: wksp-170654-1bc9c7a0

A unique identifier for the Ocean Spark workspace

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Delete Workspace

Delete an Ocean Spark workspace.

Authorizations:
auth
path Parameters
clusterId
required
string (oceanSparkClusterId)
Example: osc-20fac3f1

A unique identifier for the Ocean Spark cluster

workspaceId
required
string (oceanSparkWorkspaceId)
Example: wksp-170654-1bc9c7a0

A unique identifier for the Ocean Spark workspace

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Start Workspace

Start an Ocean Spark workspace.

Authorizations:
auth
path Parameters
clusterId
required
string (oceanSparkClusterId)
Example: osc-20fac3f1

A unique identifier for the Ocean Spark cluster

workspaceId
required
string (oceanSparkWorkspaceId)
Example: wksp-170654-1bc9c7a0

A unique identifier for the Ocean Spark workspace

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Stop Workspace

Stop an Ocean Spark workspace.

Authorizations:
auth
path Parameters
clusterId
required
string (oceanSparkClusterId)
Example: osc-20fac3f1

A unique identifier for the Ocean Spark cluster

workspaceId
required
string (oceanSparkWorkspaceId)
Example: wksp-170654-1bc9c7a0

A unique identifier for the Ocean Spark workspace

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Ocean Automatic Rightsizing

New Automatic Rightsizing version available for EKS and AKS only.

If you wish to learn more about it reach out to our support team.

Create Ocean Rightsizing Rule

Authorizations:
auth
path Parameters
oceanId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
object (Ocean Rightsizing Rule Auto Apply Definition)

Ocean Rightsizing Rule Auto Apply Configuration

excludePreliminaryRecommendations
boolean

Exclude preliminary recommendations (recommendations based on less than 4 full days of data).

object (Ocean Rightsizing Rule Recommendation Application Boundaries)

Determines the Ocean Rightsizing rule recommendation application boundaries.

object (Ocean Rightsizing Rule Recommendation Application For HPA)

HPA Rightsizing Rule Recommendation Configuration

required
Array of objects (Ocean Rightsizing Rule Recommendation Application Interval)

Determines the Ocean Rightsizing rule recommendation application intervals

object (Ocean Rightsizing Rule Recommendation Application Min Threshold)

Determines the extent of difference between current request and recommendation to trigger a change in percentage

object (Ocean Rightsizing Rule Recommendation Application Overhead Values)

Determines the Ocean Rightsizing rule recommendation application overhead values

restartReplicas
string
Enum: "MORE_THAN_ONE_REPLICA" "ALL_MANIFEST" "NO_RESTART"

Enable to sequentially restart pod batches according to recommendations, for all pods, only more than 1 replica, or not any pod.

ruleName
string

The unique name of the rule

Responses

Request samples

Content type
application/json
{
  • "ruleName": "dev-rule",
  • "restartReplicas": "ALL_MANIFEST",
  • "excludePreliminaryRecommendations": false,
  • "recommendationApplicationIntervals": [
    ],
  • "recommendationApplicationMinThreshold": {
    },
  • "recommendationApplicationBoundaries": {
    },
  • "recommendationApplicationOverheadValues": {
    },
  • "recommendationApplicationHPA": {
    },
  • "autoApplyDefinition": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

List Ocean Rightsizing Rules

Authorizations:
auth
path Parameters
oceanId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Delete Ocean Rightsizing Rules

Authorizations:
auth
path Parameters
oceanId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
ruleNames
Array of strings

Responses

Request samples

Content type
application/json
{
  • "ruleNames": [
    ]
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Ocean Rightsizing Rule

Authorizations:
auth
path Parameters
oceanId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

ruleName
required
string
Example: dev-rule

Identifier of rightsizing rule.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Update Ocean Rightsizing Rule

Authorizations:
auth
path Parameters
oceanId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

ruleName
required
string
Example: dev-rule

Identifier of rightsizing rule.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
object (Ocean Rightsizing Rule Auto Apply Definition)

Ocean Rightsizing Rule Auto Apply Configuration

excludePreliminaryRecommendations
boolean

Exclude preliminary recommendations (recommendations based on less than 4 full days of data).

object (Ocean Rightsizing Rule Recommendation Application Boundaries)

Determines the Ocean Rightsizing rule recommendation application boundaries.

object (Ocean Rightsizing Rule Recommendation Application For HPA)

HPA Rightsizing Rule Recommendation Configuration

required
Array of objects (Ocean Rightsizing Rule Recommendation Application Interval)

Determines the Ocean Rightsizing rule recommendation application intervals

object (Ocean Rightsizing Rule Recommendation Application Min Threshold)

Determines the extent of difference between current request and recommendation to trigger a change in percentage

object (Ocean Rightsizing Rule Recommendation Application Overhead Values)

Determines the Ocean Rightsizing rule recommendation application overhead values

restartReplicas
string
Enum: "MORE_THAN_ONE_REPLICA" "ALL_MANIFEST" "NO_RESTART"

Enable to sequentially restart pod batches according to recommendations, for all pods, only more than 1 replica, or not any pod.

Responses

Request samples

Content type
application/json
{
  • "restartReplicas": "ALL_MANIFEST",
  • "excludePreliminaryRecommendations": false,
  • "recommendationApplicationIntervals": [
    ],
  • "recommendationApplicationMinThreshold": {
    },
  • "recommendationApplicationBoundaries": {
    },
  • "recommendationApplicationOverheadValues": {
    },
  • "recommendationApplicationHPA": {
    },
  • "autoApplyDefinition": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Attach Ocean Rightsizing Rule

Authorizations:
auth
path Parameters
oceanId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

ruleName
required
string
Example: dev-rule

Identifier of rightsizing rule.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
Array of objects
Array
namespaceName
string

List of namespaces

Array of objects

List of workloads

Responses

Request samples

Content type
application/json
{
  • "namespaces": [
    ]
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Detach Ocean Rightsizing Rule

Authorizations:
auth
path Parameters
oceanId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

ruleName
required
string
Example: dev-rule

Identifier of rightsizing rule.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
Array of objects
Array
namespaceName
string

List of namespaces

Array of objects

List of workloads

Responses

Request samples

Content type
application/json
{
  • "namespaces": [
    ]
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Ocean Rightsizing Recommendations

Get right-sizing recommendations for an Ocean cluster.

Authorizations:
auth
path Parameters
oceanId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
object (Ocean Rightsizing Recommendation Cluster Labels)

Determines the Ocean Recommendation filtering by the combinations of namespace::workloadsLabels

object (Ocean Rightsizing Recommendation Cluster Resources)

Determines the Ocean Recommendation filtering by the combinations of namespace::workload::containers

Responses

Request samples

Content type
application/json
{
  • "clusterResources": {
    },
  • "clusterLabels": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

List Ocean Rightsizing Rollbacks

List the rightsizing rollback for ocean cluster.

Authorizations:
auth
path Parameters
oceanId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Acknowledge Rightsizing Rollbacks

Acknowledge rightsizing rollbacks For ocean cluster.

Authorizations:
auth
path Parameters
oceanId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

clusterIdentifier
required
string
Example: clusterIdentifier=dev-cluster

Identifier of cluster.

Request Body schema: application/json
Array of objects
Array
namespace
string

The namespace of the workload

resourceName
string

The name of the resource

resourceType
string

The type of the resource

Responses

Request samples

Content type
application/json
{
  • "acknowledgeRollbacks": [
    ]
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Set Cluster Recommendations Percentile

Set Recommendations Percentile for the Ocean Cluster.

This action can take a few minutes to complete.

Authorizations:
auth
path Parameters
oceanId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

clusterIdentifier
required
string
Example: clusterIdentifier=dev-cluster

Identifier of cluster.

Request Body schema: application/json
required
object non-empty
recommendationsCpuPercentile
integer
Enum: 85 90 95 99

Change the cpu percentile that the right-sizing recommendations calculation will take into account.

recommendationsMemoryPercentile
integer
Enum: 85 90 95 100

Change the memory percentile that the right-sizing recommendations calculation will take into account.

Responses

Request samples

Content type
application/json
{
  • "config": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Ocean Right-Sizing Savings

Get right-sizing savings from downsizing operations for an Ocean cluster.

Authorizations:
auth
path Parameters
oceanId
required
string
Example: o-abcd1234

Identifier of the Ocean cluster.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
endTime
required
string

End date value using either the date format "yyyy-MM-dd'T'HH:mm:ss'Z'" or ms "1494751821472".

startTime
required
string

Start date value using either the date format "yyyy-MM-dd'T'HH:mm:ss'Z'" or ms "1494751821472".

required
object (Ocean Right-Sizing Savings Workloads)

Determines the Ocean Savings filtering by the combinations of namespace::workload

Responses

Request samples

Content type
application/json
{
  • "startTime": "2025-01-20T11:35:02.745Z",
  • "endTime": "2025-01-30T11:30:01.745Z",
  • "workloads": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Elastigroup AWS

Elastigroup for Amazon Web Services (AWS)

Elastigroup Concepts and Tutorials

Create Elastigroup

Create a new AWS Elastigroup.

There are several third Party Integrations available, which can be activated based on your configuration, such as:

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
required
object

Elastigroup Configuration

required
object (Elastigroup Capacity)

Capacity Configuration

required
object (Elastigroup Compute)
description
string

Describe your AWS Elastigroup

object (Logging configuration)
name
required
string

AWS Elastigroup Name

region
required
string

The AWS region your group will be created in. This parameter is required if you specify subnets (through compute.subnetIds). This parameter is optional if you specify Availability Zones (through compute.availabilityZones).

object (Elastigroup Scaling)
object (Elastigroup Scheduling)

Schedule tasks to execute, using CRON expressions.

required
object (Elastigroup Strategy)

Strategy

object (Elastigroup Third Party Integrations)

All definitions for using third-party Integrations

Responses

Request samples

Content type
application/json
{
  • "group": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

List All Elastigroups

List all AWS Elastigroups for a Spot Account

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Update Elastigroup

Describe a specific Elastigroup JSON

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-12345

The Spot Elastigroup ID you want to update

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

autoApplyTags
boolean
Default: false
Example: autoApplyTags=true

Optionally update resource tags on the fly without performing a roll.

Request Body schema: application/json
required
object

Group

object (Elastigroup Capacity)
object (Elastigroup Compute)
description
string

Describe your AWS Elastigroup

object (Logging configuration)
name
required
string

AWS Elastigroup Name

region
string

The AWS region your group will be created in. This parameter is required if you specify subnets (through compute.subnetIds). This parameter is optional if you specify Availability Zones (through compute.availabilityZones).

object (Elastigroup Scaling)
object (Elastigroup Scheduling)

Schedule tasks to execute, using CRON expressions.

object (Elastigroup Strategy)
object (Elastigroup Third Party Integrations)

All definitions for using third-party Integrations

Responses

Request samples

Content type
application/json
{
  • "group": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Delete Elastigroup

Delete an Elastigroup AWS

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-12345

The Spot Elastigroup ID you want to update

query Parameters
accountId
string
Example: accountId=act-123abc

ID of the account associated with your token

Request Body schema: application/json
object (AMI Dellocation Options)
object (Beanstalk Dellocation Options)
object (Stateful deallocation options)

Responses

Request samples

Content type
application/json
{
  • "statefulDeallocation": {
    },
  • "beanstalk": {
    },
  • "amiBackup": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

List Elastigroup

Describe a specific Elastigroup JSON

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-12345

The Spot Elastigroup ID you want to update

query Parameters
accountId
string
Example: accountId=act-123456789

ID of the account associated with your token

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

List Stateful Instances

List all stateful instances associated with the Elastigroup

Authorizations:
auth
path Parameters
groupId
required
string

AWS Elastigroup ID

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Pause Stateful Instance

Pause a stateful instance

Authorizations:
auth
path Parameters
groupId
required
string

AWS Elastigroup ID

statefulInstanceId
required
string
Example: ssi-227a0005

Stateful instance ID

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Resume Stateful Instance

Resume a stateful instance

Authorizations:
auth
path Parameters
groupId
required
string

AWS Elastigroup ID

statefulInstanceId
required
string
Example: ssi-227a0005

Stateful instance ID

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Recycle Stateful Instance

Recycle a stateful instance AWS

Authorizations:
auth
path Parameters
groupId
required
string

AWS Elastigroup ID

statefulInstanceId
required
string
Example: ssi-227a0005

Stateful instance ID

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

De-allocate Stateful Instance

De-allocate a stateful instance – delete all the resources associated with the instance (network interface, snapshots, volumes)

Authorizations:
auth
path Parameters
groupId
required
string

AWS Elastigroup ID

statefulInstanceId
required
string
Example: ssi-227a0005

Stateful instance ID

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Delete Volume in a Stateful Instance

Delete a Volume that is part of a paused stateful instance

Authorizations:
auth
path Parameters
groupId
required
string

AWS Elastigroup ID

statefulInstanceId
required
string
Example: ssi-227a0005

Stateful instance ID

volumeId
required
string
Example: vol-0faa4b2957a3d59c8

Volume ID

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Import Stateful Instance

Create a new Stateful Elastigroup – this Elastigroup will have the same configuration and state of the imported instance.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
required
object
Array of objects

An Array holding an object of availabilityZones, this configures the availability zones the group may launch instances in. If this is not passed, the availability zone configuration is taken from the imported instance. Note: This field must be null if statefulMigrationGroup.shouldKeepPrivateIp is true, and must have a minimum of one availability zone.

name
required
string

Specify the new Elastigroup name.

originalInstanceId
required
string

The originating Instance ID. This instance will be imported along with its State.

product
string

Operation system type. Possible values: Linux/UNIX | SUSE | Linux Windows | Linux/UNIX (Amazon VPC) | SUSE Linux (Amazon VPC) | Windows (Amazon VPC).

region
string

Specify the AWS Region the instance is running in and the new Elastigroup will be created in.

shouldKeepPrivateIp
required
boolean

Setting this value to true will maintain the initial instance private IP. This will also require that the original instance be terminated in the import process incurring maintenance time. Note: This value must be false if you would like to configure availability zones and subnet ids.

shouldTerminateInstance
boolean

Decide if the instance termination should be automatic or manual. True = automatic termination. False = manual termination.

spotInstanceTypes
Array of strings

An Array holding the types of instances to be used in the Elastigroup.

Responses

Request samples

Content type
application/json
{
  • "statefulMigrationGroup": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Stateful Import Status

Get the current status of the import process. Possible values are:

  • MIGRATE_PREPARE_AWS_INSTANCE
  • MIGRATE_CREATE_IMAGE
  • MIGRATE_AWAIT_FOR_IMAGE
  • MIGRATE_AWAIT_USER_ACTION
  • MIGRATE_TERMINATE_INSTANCE
  • MIGRATE_AWAIT_INSTANCE_TERMINATION
  • MIGRATE_UPDATE_GROUP
  • MIGRATE_LAUNCH_INSTANCE
  • MIGRATE_AWAIT_INSTANCE_RUNNING
  • MIGRATE_RESUME_STATEFUL_INSTANCE
  • MIGRATE_AWAIT_STATEFUL_INSTANCE_RUNNING
  • MIGRATE_CANCEL
  • MIGRATE_FINISH
  • MIGRATE_ERROR

Authorizations:
auth
path Parameters
statefulMigrationGroupId
required
string
Example: smg-7f041234

The Process ID you want to query

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Delete Stateful Import Status

Cancel the ongoing stateful import

Authorizations:
auth
path Parameters
statefulMigrationGroupId
required
string
Example: smg-7f041234

The Process ID you want to delete

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Terminate Stateful Instance During Import Process

Manually terminate the source stateful instance during an stateful instance import.

Authorizations:
auth
path Parameters
statefulMigrationGroupId
required
string

The Process ID you want to terminate

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
object
type
string

Valid values: "terminate"

Responses

Request samples

Content type
application/json
{
  • "userAction": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Instance Lock

Set termination protection for specific instance

Authorizations:
auth
path Parameters
instanceId
required
string
Example: i-123456

AWS Instance ID

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

ttlInMinutes
integer
Example: ttlInMinutes=23

Specify a TTL (in minutes) for this lock, meaning, for how long the protection will be valid for.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Instance Unlock

Remove the termination protection from specific instance

Authorizations:
auth
path Parameters
instanceId
required
string
Example: i-123456

AWS Instance ID

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Elastigroup Status

Describes the current status of a specific Elastigroup – entailing information regarding running instance and their status

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-12345

The Spot Elastigroup ID you want to update

query Parameters
accountId
string
Example: accountId=act-123456789

ID of the account associated with your token

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Activity Events

Get historical data on events that happened in a specific Elastigroup like update, scaling activities, creation of new instances, etc.

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-12345

The Spot Elastigroup ID you want to update

query Parameters
accountId
string
Example: accountId=act-123456789

ID of the account associated with your token

fromDate
required
string
Example: fromDate=2016-10-01

Starting date to fetch the events from

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Elastilog

You can fetch a group's (Elastigroup/Ocean/Stateful Node) elastilog via the Spot API, in order to be able to consume elastilog from various tools used for log storing and analyzing. Logs have retention of 3 months back, so minimal fromDate should be up to 3 months back at runtime.

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-12345

The Spot Elastigroup ID you want to update

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

fromDate
required
string
Example: fromDate=1540036800000

Epoch number that represents the date from which to collect the log (millisecond format)

limit
string
Example: limit=i-12345678

Maximum number of lines to extract in a response. Max value allowed - 1000. Default: 500

resourceId
string
Example: resourceId=i-12345678

Filter extracted log entries for a specific resource id. Default: Null

severity
string
Example: severity=ALL

Severity of log entries to extract. Valid Values: ALL, INFO,DEBUG,WARN. Default: ALL

toDate
required
string
Example: toDate=1542715200000

Epoch number that represents the date until which log is collected (millisecond format)

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Update Capacity

Update the capacity of an Elastigroup

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-12345

The Spot Elastigroup ID you want to update

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
object (Capacity)
maximum
integer
Default: 0

Number that indicates minimum instance amount

minimum
integer
Default: 0

Number that indicates minimum instance amount

target
integer
Default: 0

Number that indicates amount of desired instances

Responses

Request samples

Content type
application/json
{
  • "capacity": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Scale Up

Add instances to your Elastigroup

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-12345

The Spot Elastigroup ID you want to update

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

adjustment
integer
Example: adjustment=1

The number of instances to add to the Elastigroup

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Scale Down

Remove instances from your Elastigroup. Note - Scale Advanced expression Remove instances from your Elastigroup

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-12345

The Spot Elastigroup ID you want to update

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

adjustment
integer
Example: adjustment=1

The number of instances to add to the Elastigroup

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Suspend Scaling Policies

Suspend processes inside your Elastigroup

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-12345

The Spot Elastigroup ID you want to update

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

policyName
required
string
Example: policyName=Example Policy Name

Policy Name of scaling policy to suspend

Request Body schema: application/json
object (Suspension)
ttlInMinutes
integer

Set TTL in minutes. min value: 1 (one minute). max value: 10080 (one week)

Responses

Request samples

Content type
application/json
{
  • "suspension": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Suspend Processes

Suspend processes inside your Elastigroup

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-12345

The Spot Elastigroup ID you want to update

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
One of
processes
Array of strings

The names of the processes that will be suspended. Valid values are: AUTO_SCALE, AUTO_HEALING, OUT_OF_STRATEGY, PREVENTIVE_REPLACEMENT, REVERT_PREFERRED, SCHEDULING

Responses

Request samples

Content type
application/json
Example
{
  • "processes": [
    ]
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

List Suspended Processes

List all active Suspended processes for specific Elastigroup

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-12345

The Spot Elastigroup ID you want to update

query Parameters
accountId
string
Example: accountId=act-123456789

ID of the account associated with your token

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Remove Suspended Processes

Remove active suspension from Elastigroup

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-12345

The Spot Elastigroup ID you want to update

query Parameters
accountId
string
Example: accountId=act-123456789

ID of the account associated with your token

Request Body schema: application/json
processes
Array of strings (Processes)

The list of processes to remove from suspension. Valid values are: AUTO_SCALE, AUTO_HEALING, OUT_OF_STRATEGY, PREVENTIVE_REPLACEMENT, REVERT_PREFERRED, SCHEDULING

Responses

Request samples

Content type
application/json
{
  • "processes": [
    ]
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

List Suspended Scaling Policies

Suspended scaling policies inside your Elastigroup

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-12345

The Spot Elastigroup ID you want to update

query Parameters
accountId
string
Example: accountId=act-123456789

ID of the account associated with your token

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Remove Suspended Scaling Policies

Resume suspended scaling policies inside your Elastigroup

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-12345

The Spot Elastigroup ID you want to update

query Parameters
accountId
string
Example: accountId=act-123456789

ID of the account associated with your token

policyName
string
Example: policyName=policy_1

Name of the suspended scaling policy to remove from suspension

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Costs per Elastigroup

Get financial information on a specific Elastigroup, return only Spot costs.

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-12345

The Spot Elastigroup ID you want to update

query Parameters
accountId
string
Example: accountId=act-123abc

ID of the account associated with your token

aggregationPeriod
string
Example: aggregationPeriod=daily

Optional. The time period over which data is aggregated. Can only be "daily". For example, the figures in each data set are per day

fromDate
required
string
Example: fromDate=2018-06-20

Data values following either a date format (YYYY-MM-DDTHH:mm:ss.SSSZ ; 2016-01-10T00:00:00.000Z) or Unix seconds Timestamp (1494751821)

toDate
required
string
Example: toDate=2018-11-20

Data values following either a date format (YYYY-MM-DDTHH:mm:ss.SSSZ ; 2016-01-10T00:00:00.000Z) or Unix seconds Timestamp (1494751821)

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Detailed Cost

Get detailed financial information on a specific Elastigroup, for all lifecycles.

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-12345

The Spot Elastigroup ID you want to update

query Parameters
accountId
string
Example: accountId=act-123abc

ID of the account associated with your token

aggregationPeriod
string
Example: aggregationPeriod=daily

Optional. The time period over which data is aggregated. Can only be "daily". For example, the figures in each data set are per day

fromDate
required
string
Example: fromDate=2018-06-20

Data values following either a date format (YYYY-MM-DDTHH:mm:ss.SSSZ ; 2016-01-10T00:00:00.000Z) or Unix seconds Timestamp (1494751821)

toDate
required
string
Example: toDate=2018-11-20

Data values following either a date format (YYYY-MM-DDTHH:mm:ss.SSSZ ; 2016-01-10T00:00:00.000Z) or Unix seconds Timestamp (1494751821)

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Instance Status

Get the current instance status Possible status values - Active and Terminating

Authorizations:
auth
path Parameters
instanceId
required
string
Example: i-123456

The instance ID you want to query

query Parameters
accountId
string
Example: accountId=act-123abc

ID of the account associated with your token

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Import EC2 Instance

Import an EC2 instance into a new Elastigroup

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

instanceId
required
string
Example: instanceId=i-008a13360040aa88e

Enter the AWS instance Id of the instance to import

region
required
string
Example: region=us-east-2

The AWS region to create the new Elastigroup in

Request Body schema: application/json
object (Group)
name
string

The name of the new Elastigroup

spotInstanceTypes
Array of strings

Optionally provide a list of spot instance types to improve spot market availability for the Elastigroup. Overrides the imported instance type.

Responses

Request samples

Content type
application/json
{
  • "group": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

AMI Backup

Get status of a specific deployment

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-12345

The Spot Elastigroup ID you want to update

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Instance Healthiness

Get a list of instances with health status. In case a shutdown script is configured for the group, it will also retrieve the Spot Agent health status.

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-12345

The Spot Elastigroup ID you want to update

query Parameters
accountId
string
Example: accountId=act-123abc

ID of the account associated with your token

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Detach Instance

Detach instances from your Elastigroup

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-12345

The Spot Elastigroup ID you want to update

query Parameters
accountId
string
Example: accountId=act-123abc

ID of the account associated with your token

Request Body schema: application/json
drainingTimeout
integer (Time)

Draining Timeout

instancesToDetach
object (Instances to be detached)

Instances to be detached

shouldDecrementTargetCapacity
boolean (Decrement target capacity criteria)

Should Decrement Target Capacity Criteria

shouldTerminateInstances
boolean (Termination criteria)

Should Terminate Instances Criteria

Responses

Request samples

Content type
application/json
{
  • "instancesToDetach": [
    ],
  • "shouldTerminateInstances": true,
  • "shouldDecrementTargetCapacity": false,
  • "drainingTimeout": 300
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Import ASG

Create a new Elastigroup – this Elastigroup will have the same configuration of the imported Autoscaling group

Authorizations:
auth
query Parameters
accountId
string
Example: accountId=act-12345

Your account ID in Spot

autoScalingGroupName
required
string
Example: autoScalingGroupName=MyASG

The ASG name

dryRun
boolean
Example: dryRun=true

When dryRun is set to true, the API call will return the Elastigroup configuration without actually performing any action

region
required
string
Example: region=us-east-1

The AWS region for the ASG

Request Body schema: application/json
object (Group)
availabilityVsCost
string
Default: "balanced"
Enum: "costOriented" "availabilityOriented" "balanced" "cheapest" "equalAzDistribution"

How Elastigroup determines which instances to add and replace. (please read this article before using Equal AZ Instance Distribution)

name
string (Name)

The name of the Elastigroup to be created

product
string (Product (OS))

Operation system type. Possible values: Linux/UNIX | SUSE | Linux Windows | Linux/UNIX (Amazon VPC) | SUSE Linux (Amazon VPC) | Windows (Amazon VPC)

spotInstanceTypes
Array of strings (Product (OS))

An Array holding the types of instances to be used in the Elastigroup

Responses

Request samples

Content type
application/json
{
  • "group": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Instance Type By Region

Get the available spot instances types available in a specific region

Authorizations:
auth
query Parameters
region
required
string
Example: region=us-east-2

The AWS region

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Simulate an Instance Interruption

The simulate instance interruption API is used for simulating a spot interruption in AWS, so that customers can verify specific applicative behaviors in case an interruption takes place. Once the interruption api is called, instances posted in the API body will be terminated in AWS, thus mocking a spot interruption.

Authorizations:
auth
query Parameters
accountId
string
Example: accountId=act-123abc

ID of the account associated with your token

Request Body schema: application/json
instancesToInterrupt
Array of strings

A list of group's instance ids to interrupt

Responses

Request samples

Content type
application/json
{
  • "instancesToInterrupt": [
    ]
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Create Instance Signal

The instance signal API is used for notifying Spot about the instance state, so Spot can act accordingly. Supported signals are - INSTANCE_READY – Whenever this signal is sent, Spot will register the instance to the ELB INSTANCE_READY_TO_SHUTDOWN – Whenever this signal is sent, Spot will terminate the instance after it was marked for termination. Important - You need to define the expected signals for your Elastigroup in the group configuration.

Authorizations:
auth
query Parameters
accountId
string
Example: accountId=act-123abc

ID of the account associated with your token

Request Body schema: application/json
instanceId
string

The instance ID the signal refers to.

signal
string

The specific signal you want to trigger. Valid Values - INSTANCE_READY, INSTANCE_READY_TO_SHUTDOWN

Responses

Request samples

Content type
application/json
{
  • "instanceId": "i-123456",
  • "signal": "INSTANCE_READY"
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Instance Standby

Instance Standby enables you to put an instance in Standby state , update or troubleshoot the instance, and then return the instance to service. Instances that are on standby are still part of the Elastigroup, but they don't get application traffic. Whenever instance is standby state - It will be de-registered from all the ELBs / ALBs in the Elastigroup It won't be affected from Scale down activities in the Elastigroup The instance health won't be checked, and it won't be replaced When the instance exits the Standby state - The instance will be register back to all the ELBs / ALBs that are defined in the Elastigroup It will be considered and affected from all the Elastigroup activities (helth checks, scaling, etc.)

Authorizations:
auth
path Parameters
instanceId
required
string
Example: i-123456

The instance ID you want to put in standby state

query Parameters
accountId
string
Example: accountId=act-123abc

ID of the account associated with your token

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Exit Instance Standby

Exit standby by mode

Authorizations:
auth
path Parameters
instanceId
required
string
Example: i-123456

The instance ID you want to put in standby state

query Parameters
accountId
string
Example: accountId=act-123abc

ID of the account associated with your token

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Group's Deployments Status

Get list of all the deployments of a specific Elastigroup and their status

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-12345

The Spot Elastigroup ID you want to update

query Parameters
accountId
string
Example: accountId=act-123abc

ID of the account associated with your token

limit
integer
Example: limit=5

Limits results

sort
string
Example: sort=createdAt:ASC

Field to sort by the results Default: createdAt:DESC

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Start Deployment

Deploy your Elastigroup (triggers Blue/Green Deployment that replaces the existing instances in the Elastigroup)

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-12345

The Spot Elastigroup ID you want to update

query Parameters
accountId
string
Example: accountId=act-123abc

ID of the account associated with your token

Request Body schema: application/json
batchSizePercentage
required
integer

Indicates (in percentage) the batch size of the deployment (meaning, how many instances to replace in each batch)

drainingTimeout
integer >= 0
Default: 120

Indicates (in seconds) the timeout to drain the instances. Override the group value.

gracePeriod
required
integer

Indicates (in seconds) the timeout to wait until instance become healthy based on the healthCheckType

healthCheckType
string
Enum: "ELB" "ECS_CLUSTER_INSTANCE" "TARGET_GROUP" "OPSWORKS" "NOMAD_NODE" "HCS" "EC2" "NONE"

Define a health check type.
If no value is set the roll will use the group’s auto-healing health check.

object

The roll strategy

Responses

Request samples

Content type
application/json
{
  • "batchSizePercentage": 20,
  • "gracePeriod": 300,
  • "healthCheckType": "EC2",
  • "drainingTimeout": 60,
  • "strategy": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Stop Deployment

Stop an existing deployment

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-12345

The Spot Elastigroup ID you want to update

rollId
required
string
Example: sbgd-9876

The deployment ID you want to stop

query Parameters
accountId
string
Example: accountId=act-123abc

ID of the account associated with your token

Request Body schema: application/json
object (Role)
status
string (Status)

Set the status of the group to `STOPPED"

Responses

Request samples

Content type
application/json
{
  • "roll": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Deployment Status

Get status of a specific deployment

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-12345

The Spot Elastigroup ID you want to update

rollId
required
string
Example: sbgd-9876

The deployment ID you want to query

query Parameters
accountId
string
Example: accountId=act-123abc

ID of the account associated with your token

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Deployment Actions

Apply a Detach action to a deployment

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-12345

The Spot Elastigroup ID you want to update

rollId
required
string
Example: sbgd-9876

The deployment ID to call the action on

query Parameters
accountId
string
Example: accountId=act-123abc

ID of the account associated with your token

Request Body schema: application/json
actionType
string (Type of action)

Sets the action that will take place, Accepted values are: DETACH_OLD, DETACH_NEW

drainingTimeout
integer (Draining timeout criteria)

Indicates (in seconds) the timeout to wait until instance are detached

shouldDecrementTargetCapacity
boolean (Should Decrement Target Capacity criteria)
Default: true
shouldHandleAllBatches
boolean (Should Hnadle All Batches Criteria)
Default: false

Indicator if the action should apply to all batches of the deployment or only the latest batch

Responses

Request samples

Content type
application/json
{
  • "actionType": "DETACH_NEW",
  • "shouldHandleAllBatches": true,
  • "drainingTimeout": 200,
  • "shouldDecrementTargetCapacity": true
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

ECS Initiate Cluster Roll

Initiate a cluster roll for an Elastigroup with ECS cluster

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-12345

Elastigroup ID

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
required
object
batchMinHealthyPercentage
integer
Default: 50

Indicates the threshold of minimum healthy instances in single batch. If the amount of healthy instances in single batch is under the threshold, the cluster roll will fail. If exists, the parameter value will be in range of 1-100. In case of null as value, the default value in the backend will be 50%. Value of param should represent the number in percentage (%) of the batch.

batchSizePercentage
required
integer

Size of patch for roll as a percent

comment
string

Add a comment description for the roll. comment should be limit to 256 chars.

Responses

Request samples

Content type
application/json
{
  • "roll": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

ECS Update Cluster Roll Status

Update a running ECS cluster roll status

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-12345

Elastigroup ID

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
required
object
status
required
string

Valid values: "STOPPED"

Responses

Request samples

Content type
application/json
{
  • "roll": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

ECS Get All Cluster Rolls Per Elastigroup

Get status for every ECS cluster rolls in given Elastigroup

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-12345

Elastigroup ID

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

ECS Get Cluster Roll Status by Roll ID

Get status for specific ECS cluster rolls in given Elastigroup

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-12345

Elastigroup ID

rollId
required
string

The cluster roll ID you want to query

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Start Beanstalk Maintenance

Put your Beanstslk Elastigroup into maintenance mode, before you start updating the beanstalk configuration.

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-12345

The Spot Elastigroup ID

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Finish Beanstalk Maintenance

Finish maintenance mode, and trigger a blue-green deployment.

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-12345

Elastigroup ID

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Beanstalk Maintenance Status

Get the group maintenance status.

  • If the status is ACTIVE: putting the group in maintenance mode is allowed.
  • If the status is AWAIT_USER_UPDATE: the group is pending for manually finishing maintenance mode.
  • If the status is CANCELING_MAINTENANCE_MODE: the group is in the process of canceling maintenance mode.
Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-12345

Elastigroup ID

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Beanstalk Configuration

  • Get your Beanstalk environment configuration from AWS. This call is typically used as the initial step in importing your existing Beanstalk configuration to an Elastigroup.
  • Note: To optimize the availability of your Beanstalk workload on Elastigroup, instance types similar to those running in your existing configuration are automatically added to the response under instanceTypes. Should these instance types not meet your requirements you may remove them.
Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

environmentId
required
string
Example: environmentId=e-12345

The Beanstalk name

region
required
string
Example: region=us-east-1

The AWS region for the Beanstalk

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Beanstalk Reimport

Re-import the beanstalk configuration

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-12345

Elastigroup ID

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Create CodeDeploy B/G Deployment

Trigger a Blue-Green deployment to your Elastigroup, this will initiate a deployment that will replace the existing instances(blue) with new ones(green).

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-12345

Elastigroup ID

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
object
Array of objects
Array of objects
timeout
integer

Responses

Request samples

Content type
application/json
{
  • "deployment": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get CodeDeploy B/G Deployment

Get CodeDeploy Elastigroup deployment status for more information see: CodeDeploy B/G Deployment

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-12345

Elastigroup ID

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
object
Array of objects
Array of objects
timeout
integer

Responses

Request samples

Content type
application/json
{
  • "deployment": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

List Elastigroup ITF Listener Rule Migrations

Get all ITF listener rule migrations of a specific Elastigroup.

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-12345

The Spot Elastigroup ID you want to update

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Update ITF Listener Rule Migration

Update an ITF listener rule migration object of a specific Elastigroup.

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-12345

The Spot Elastigroup ID you want to update

migrationId
required
string
Example: ilrm-12345678

The ID of the ITF listener rule migration to be updated.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
status
string
Value: "USER_RETRY"

The status to be updated. Valid value is "USER_RETRY".

Responses

Request samples

Content type
application/json
{
  • "status": "USER_RETRY"
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Elastigroup AWS EMR Scaler

List All Scalers

List all MR Scalers and their configuration.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Create Scaler

Create a new EMR cluster.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
required
object
object (EMR Cluster Object)

Allowed only when the new strategy is chosen.

object (Compute Object)

describes the compute resources for the MR scaler

description
string

description for the MRScaler

name
required
string

MRScaler name

region
required
string

The region of the source cluster

object (Scaling Object)

Set scaling polices.

object (Scheduling Object)

Schedule tasks to execute on the Elastigroup.

required
object (Strategy Object)

The strategy for creating the group. At least one of wrapping, cloning, or new is required.

Array of objects (Termination Policy Object)

Termination policies for EMR clusters based on CloudWatch Metrics.

Responses

Request samples

Content type
application/json
{
  • "mrScaler": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Create Scaler Operator

mrScaler – required will have the same configuration as in createMrScaler with one exception: we will only work with strategy of “new”, no “clone”/”warp” will be allowed.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
required
object
name
string

Responses

Request samples

Content type
application/json
{
  • "name": "GuyEmrOperatorTest",
  • "mrScaler": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Scaler

Get a description of a specific MR Scaler and its configuration.

Authorizations:
auth
path Parameters
mrScalerId
required
string
Example: simrs-12223

The MRScaler ID

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Update Scaler

Update an MR Scaler. Partial updating is supported.

Authorizations:
auth
path Parameters
mrScalerId
required
string
Example: simrs-12223

The MRScaler ID

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
One of
object

MR Scaler Object - Update Task Capacity

object
object
object
object
maximum
integer
minimum
integer
target
integer

Responses

Request samples

Content type
application/json
Example
{
  • "mrScaler": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Delete Scaler

Delete an MR Scaler

Authorizations:
auth
path Parameters
mrScalerId
required
string
Example: simrs-12223

The MRScaler ID

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

List Instances

Get a list of all instances and instances groups in the cluster

Authorizations:
auth
path Parameters
mrScalerId
required
string
Example: simrs-12223

The MRScaler ID

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Scale Up

Scale up MR Scaler instances

Authorizations:
auth
path Parameters
mrScalerId
required
string
Example: simrs-12223

The MRScaler ID

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

adjustment
required
integer
Example: adjustment=3

Number of instances to add to the MR Scaler

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Scale Down

Scale down MR Scaler instances

Authorizations:
auth
path Parameters
mrScalerId
required
string
Example: simrs-12223

The MRScaler ID

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

adjustment
required
integer
Example: adjustment=3

Number of instances to remove from the MR Scaler

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

List Scalers

Get MR Scaler cluster

Authorizations:
auth
path Parameters
mrScalerId
required
string
Example: simrs-12223

The MRScaler ID

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Scaler Costs

Get financial information on the MR Scaler, including running time, costs, and savings

Authorizations:
auth
path Parameters
mrScalerId
required
string
Example: simrs-12223

The MRScaler ID

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

fromDate
required
string
Example: fromDate=2020-09-01 or fromDate=1598918400000

Get items on or after this date (ISO 8601 or Unix timestamp)

toDate
required
string
Example: toDate=2020-09-01 or fromDate=1598918400000

Get items on or before this date (ISO 8601 or Unix timestamp)

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Elastigroup GCP

Elastigroup for Google Cloud

Elastigroup Concepts and Tutorials

List Elastigroups

List all GCP Elastigroups for a Spot Account

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Create Elastigroup

Create a new GCP Elastigroup

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
required
object (GCP Elastigroup)
required
object (Capacity Units)
required
object (Compute Object)
createdAt
string <date-time>

The datetime the group was created.

description
string

Description for your GCP Elastigroup

name
required
string

GCP Elastigroup Name

object (Scaling object)
object (Scheduling Object)
required
object (Elastigroup Strategy)
object (Third Parties Integration Object)
updatedAt
string <date-time>

The datetime the group was last updated.

Responses

Request samples

Content type
application/json
{
  • "group": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Elastigroup

List all properties for single GCP Elastigroup

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-12345

Elastigroup ID

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Delete Elastigroup

Delete an Elastigroup GCP

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-12345

Elastigroup ID

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Update Elastigroup

Update an GCP Elastigroup

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-12345

The Spot Elastigroup ID you want to update

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
required
object (GCP Elastigroup)

Elastigroup Configuration

object (Capacity Units)

Update capacity settings

object (Compute Object)

Compute Configuration

description
string

Description for your GCP Elastigroup

name
string

GCP Elastigroup Name

object (Scaling object)

Update scaling settings

object (Scheduling Object)

Schedule tasks to execute, using CRON expressions.

object (Elastigroup Strategy)

Update strategy settings

object (Third Parties Integration Object)

Third Parties Integration Configuration

Responses

Request samples

Content type
application/json
{
  • "group": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Elastigroup Status

Get the status for all instances that are memebers of the Elastigroup

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-12345

Elastigroup ID

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

List Activity Events

Get all activity events for the Elastigroup

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-12345

Elastigroup ID

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

fromDate
required
string <date-time>
Example: fromDate=2019-05-17

Get items on or after this date (ISO 8601)

toDate
required
string <date-time>
Example: toDate=2019-05-25

Get items on or before this date (ISO 8601)

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Elastilog

Fetch a group's Elastilog

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-12345

Elastigroup ID

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

fromDate
required
string
Example: fromDate=2020-09-01 or fromDate=1598918400000

Get items on or after this date (ISO 8601 or Unix timestamp)

limit
integer <= 1000
Default: 500
Example: limit=200

Maximum number of items to return.

toDate
required
string
Example: toDate=2020-09-01 or fromDate=1598918400000

Get items on or before this date (ISO 8601 or Unix timestamp)

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Scale Up

Add instances to the Elastigroup

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-12345

The Spot Elastigroup ID you want to update

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

adjustment
required
integer
Example: adjustment=1

The number of instances to add to the group

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Scale Down

Remove instances from the Elastigroup

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-12345

The Spot Elastigroup ID you want to update

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

adjustment
required
integer
Example: adjustment=1

The number of instances to remove from the group

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Costs Per Account

Retrieve costs up to one year back per specified account over a specified time period.

Authorizations:
auth
query Parameters
accountId
string
Example: accountId=act-12345678

The Spot account ID for which the cost information should be returned.

fromDate
string
Example: fromDate=2016-01-10T00:00:00.000Z
toDate
string
Example: toDate=2016-01-10T01:00:00.000Z

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Elastigroup Costs

Get financial information on a specific Elastigroup

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-12345

Elastigroup ID

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

fromDate
required
string
Example: fromDate=2020-09-01 or fromDate=1598918400000

Get items on or after this date (ISO 8601 or Unix timestamp)

toDate
required
string
Example: toDate=2020-09-01 or fromDate=1598918400000

Get items on or before this date (ISO 8601 or Unix timestamp)

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

List Deployments

Get all of the deployments for a specific Elastigroup, and their status

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-12345

Elastigroup ID

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Start Deployment

Deploy the Elastigroup: Triggers a Blue/Green deployment that replaces the existing instances in the Elastigroup

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-12345

Elastigroup ID

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
batchSizePercentage
required
integer

(in percentage) the batch size of the deployment, i.e.: how many instances to replace in each batch

gracePeriod
required
integer

(in seconds) the time until an instance becomes healthy in the load balancer

Responses

Request samples

Content type
application/json
{
  • "batchSizePercentage": 20,
  • "gracePeriod": 300
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Deployment

Get a specific deployment's status

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-12345

The Spot Elastigroup ID you want to update

rollId
required
string

The deployment ID to query

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Stop Deployment

Stop an existing deployment

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-12345

The Spot Elastigroup ID you want to update

rollId
required
string

The deployment ID to query

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
object
status
string

in this case, always set to "STOPPED"

Responses

Request samples

Content type
application/json
{
  • "roll": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Detach Instances

Detach instances from an Elastigroup

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-12345

Elastigroup ID

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
drainingTimeout
integer

(Applies only if shouldTerminateInstances is on) The draining timeout (in seconds) before terminating the instance. If no draining timeout is defined, the group's draining timeout applies.

instancesToDetach
Array of strings

The names of the instances to detach from the group.

shouldDecrementTargetCapacity
boolean

Indicates whether to decrement the capacity of the group, so no new instance will be launched instead of the detached one.

shouldTerminateInstances
boolean

Indicates whether to terminate the instances or not.

Responses

Request samples

Content type
application/json
{
  • "instancesToDetach": [
    ],
  • "shouldTerminateInstances": true,
  • "shouldDecrementTargetCapacity": true,
  • "drainingTimeout": 0
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Instance Status

Get the current instance status. Possible status values: ACTIVE, TERMINATING

Authorizations:
auth
path Parameters
instanceId
required
string

GCP Instance ID

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Lock Instance

Set termination protection for a specific instance.

Authorizations:
auth
path Parameters
instanceId
required
string

GCP Instance ID

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

ttlInMinutes
required
string

Specify a TTL (in minutes) for this lock, i.e.: for how long the protection will be valid for.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Unlock Instance

Remove termination protection for a specific instance.

Authorizations:
auth
path Parameters
instanceId
required
string

GCP Instance ID

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Elastigroup Azure Spot VMs

Elastigroup for Microsoft Azure

Elastigroup Concepts and Tutorials

Update Elastigroup

Update an Azure Elastigroup cluster.

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-123123

Elastigroup's ID

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
required
object (Azure Elastigroup)
object (Capacity)

Capacity of Elastigroup.

object (Elastigroup Compute Update)

Compute settings for Elastigroup.

description
string

Describe your Azure Elastigroup

object (Elastigroup Health)

Set health check and auto-healing of unhealthy VMs.

object (Elastigroup Integrations)

Configure integrations for the VMs in the Elastigroup.

name
string

Azure Elastigroup Name

object (Elastigroup Scaling)

Scaling Policies for Elastigroup.

object (Stateless Group Scheduling)

Define cron-based scheduled tasks.

object (Elastigroup Strategy)

Strategy for Elastigroup.

Responses

Request samples

Content type
application/json
{
  • "group": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Elastigroup

List an Elastigroup cluster.

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-12345

The Spot Elastigroup ID you want to update

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Delete Elastigroup

Delete an Elastigroup cluster.

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-12345

The Spot Elastigroup ID you want to update

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Update Capacity

Update the capacity of an Elastigroup

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-12345

The Spot Elastigroup ID you want to update

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
object (Capacity)

Capacity of Elastigroup.

maximum
integer >= 0

Maximum number of VMs.

minimum
integer >= 0

Minimum number of VMs.

target
integer >= 0

Desired number of VMs for Elastigroup to maintain.

Responses

Request samples

Content type
application/json
{
  • "capacity": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Create Elastigroup

Create a new Elastigroup cluster.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
required
object (Azure Elastigroup)

Azure Elastigroup Configuration

required
object

Capacity of Elastigroup

required
object (Compute)

Elastigroup's Compute Configurtion

description
string

Describe your Azure Elastigroup

object (Health)

Set health check and auto-healing of unhealthy VMs.

object (Elastigroup Integrations)

Configure integrations for the VMs in the Elastigroup.

name
required
string

Azure Elastigroup Name

region
required
string

Valid Azure region the Elastigroup is managed in

resourceGroupName
required
string

The Azure resource group to associate the Elastigroup with

object (Azure Scaling)

Scaling Policies for Elastigroup. Set as many policies as needed to maximize the Elastigroup’s efficiency.

object

Define cron-based scheduled tasks.

required
object (Scaling Strategy)

Responses

Request samples

Content type
application/json
{
  • "group": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

List Elastigroups

List Elastigroup clusters.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

name
string
Example: name=TestGroup

Filters to find the Elastigroup via a specific name.

region
string
Example: region=eastus

Filters to find all the groups in a specific region.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Elastigroup Status

Get status of Elastigroup cluster.

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-12345

The Spot Elastigroup ID you want to update

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Vm Healthiness

Get a list of vms with health status.

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-123123

Elastigroup's ID

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Suspend Group

Suspends the Group.

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-12345

The Spot Elastigroup ID you want to update

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
required
Array of objects

List of processes to create or update their suspensions

Array
name
required
string
Enum: "autoHealing" "signalTimeout" "autoScale" "scaleDown" "syncStrategy" "preventiveReplacement"

Process name to create signal timeout

ttlInMinutes
integer >= 0

The duration in minutes which the process is suspended for;
if not provided, then it will remain suspended until resumed

Responses

Request samples

Content type
application/json
{
  • "processes": [
    ]
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Resume Group

Resumes the Group.

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-12345

The Spot Elastigroup ID you want to update

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
required
Array of objects

List of processes to cancel their suspensions

Array
name
required
string
Enum: "autoHealing" "signalTimeout" "autoScale" "scaleDown" "syncStrategy" "preventiveReplacement"

Process name to create signal timeout

Responses

Request samples

Content type
application/json
{
  • "processes": [
    ]
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Detach VMs

Scale down specific virtual machines in Elastigroup cluster.

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-12345

The Spot Elastigroup ID you want to update

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
drainingTimeout
string
Default: 120

The time in seconds to allow the virtual machine be be drained from incoming TCP connections and detached from MLB before terminating it.

shouldDecrementTargetCapacity
required
boolean

Prevent Elastigroup from scaling back to target capacity when virtual machines are detached.

shouldDeregisterVmFromLb
boolean
Default: true

Indicates whether to deregister the stateful node's VM from any type of load balancer. Will only be applied if the shouldTerminateVms is 'false'

shouldTerminateVms
required
boolean

Whether to terminate the VMs or not.

vmsToDetach
required
Array of strings

Array of virtual machine names to detach.

Responses

Request samples

Content type
application/json
{
  • "vmsToDetach": [
    ],
  • "shouldTerminateVms": true,
  • "shouldDecrementTargetCapacity": true,
  • "shouldDeregisterVmFromLb": true,
  • "drainingTimeout": 300
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Scale Down

Scale down virtual machines in Elastigroup cluster.

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-12345

The Spot Elastigroup ID you want to update

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

adjustment
required
integer >= 1
Example: adjustment=5

Number of VMs to scale down

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Scale Up

Scale up virtual machines in Elastigroup cluster.

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-12345

The Spot Elastigroup ID you want to update

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

adjustment
required
integer >= 1
Example: adjustment=5

Number of VMs to scale up

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Start Deployment

Deploy the Elastigroup. This triggers a Blue/Green deployment that replaces the existing VMs in the Elastigroup.

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-12345

The Spot Elastigroup ID you want to update

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
object (groupVmDeployment)
batchMinHealthyPercentage
integer [ 1 .. 100 ]
Default: 50

Indicates the threshold of minimum healthy virtual machines in a single batch.
If the amount of healthy virtual machines in a single batch is under the threshold, the deployment will fail.
The value of the parameter should represent the number in percentage (%) of the batch.

batchSizePercentage
integer [ 1 .. 100 ]
Default: 25

Indicates (in percentage) the batch size of the deployment (meaning, how many nodes to replace in each batch).
Cannot be null.

drainingTimeout
integer >= 0

Indicates (in seconds) the timeout to drain the instances. Can be null.
Default - The Elastigroups draining time out or 120.

gracePeriod
integer >= 300
Default: 600

Indicates (in seconds) the timeout to wait until the node becomes healthy.

healthCheckTypes
Array of strings
Items Enum: "vmState" "applicationGateway"

Define a health check type. Can be null.
If no value is set, the deployment will use the group's auto-healing health check.

Responses

Request samples

Content type
application/json
{
  • "deployment": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get All Deployments

Get a list of all the deployments of a specific Elastigroup and the status of each one.

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-12345

The Spot Elastigroup ID you want to update

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

LIMIT
integer
Example: LIMIT=14

Limits the number of deployments returned. Default: 5

SORT
string
Example: SORT=createdAt:DESC

Field by which to sort the results. Default: createdAt:DESC

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Deployment

Get the status of a specific deployment.

Authorizations:
auth
path Parameters
deploymentId
required
string
Example: sbgd-9876

The deployment ID you want to query.

groupId
required
string
Example: sig-12345

The Spot Elastigroup ID you want to update

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Deployment Status

Get the detailed status of a specific deployment. This includes status details per batch and other information.

Authorizations:
auth
path Parameters
deploymentId
required
string
Example: sbgd-9876

The deployment ID you want to query.

groupId
required
string
Example: sig-12345

The Spot Elastigroup ID you want to update

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Import Group From Scale Set

Given a scale set, constructs a valid group configuration based on the scale set and returns it.

Authorizations:
auth
path Parameters
resourceGroupName
required
string
Example: ExampleResourceGroup

Resource Group Name - Must be valid.

scaleSetName
required
string
Example: MyExampleScaleSetImport

Scale Set Name - Must be valid

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Import Group From Virtual Machine

Given a virtual machine, constructs a valid group configuration based on the virtual machine and returns it.

Authorizations:
auth
path Parameters
resourceGroupName
required
string
Example: ExampleResourceGroup
virtualMachineName
required
string
Example: MyExampleVirtualMachineImport
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Import Group From Load Balancer

Given a load balancer, constructs a valid group configuration and returns it.

Authorizations:
auth
path Parameters
backendPoolName
required
string
Example: MyExampleBackendPoolName
loadBalancerName
required
string
Example: MyExampleLoadBalancerImport
resourceGroupName
required
string
Example: ExampleResourceGroup
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Import Group From Application Gateway

Given an application gateway, constructs a valid group configuration and returns it.

Authorizations:
auth
path Parameters
applicationGatewayName
required
string
Example: MyExampleApplicationGatewayImport
backendPoolName
required
string
Example: MyExampleBackendPoolName
resourceGroupName
required
string
Example: ExampleResourceGroup
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Create VM Signal

The VM signal API is used for notifying Spot about the VM state so that Spot can act accordingly. Supported signals are vmReady – Whenever this signal is sent, Spot will register the instance to the relevant Load Balancer and Application Gateway. vmReadyToShutdown – When this signal is received after a vm is detached; we will immediately terminate the vm. You must define the expected signals for your Elastigroup in the group configuration.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
resourceGroupName
required
string

This is the resource group of the Elastigroup or Stateful Node.

signalType
required
string
Enum: "vmReady" "vmReadyToShutdown"

The specific signal you want to trigger.

vmName
required
string

The virtual machine ID the signal refers to.

Responses

Request samples

Content type
application/json
{
  • "vmName": "vm-123456",
  • "signalType": "vmReady",
  • "resourceGroupName": "TestResourceGroup"
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Virtual Machine Protection

Protect virtual machines in Elastigroup cluster.

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-12345

The Spot Elastigroup ID you want to update

vmName
required
string
Example: i-f2a44ba41875

The virtual machine name to protect.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

ttlInMinutes
integer
Example: ttlInMinutes=180

Specify a TTL (in minutes) for this protection, meaning, for how long the protection will be valid for. (If null, infinite protection)

Responses

Response samples

Content type
application/json
{
  • "response": {
    }
}

Virtual Machine Remove Protection

Un-Protect virtual machines in Elastigroup cluster.

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-12345

The Spot Elastigroup ID you want to update

vmName
required
string
Example: i-f2a44ba41875

The virtual machine name to remove protection.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "response": {
    }
}

Get Elastilog

You can fetch a Elastigroup's Elastilog via the Spot API, in order to be able to consume elastilog from various tools used for log storing and analyzing. Logs have retention of 3 months back from today, so minimal fromDate should be up to 3 months back at runtime.

Authorizations:
auth
path Parameters
groupId
required
string
Example: sig-12345

The Spot Elastigroup ID you want to update

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

fromDate
required
string
Example: fromDate=2020-09-01 or fromDate=1598918400000

Get items on or after this date (ISO 8601 or Unix timestamp)

limit
integer [ 0 .. 1000 ]
Example: limit=500

Maximum number of lines to extract in a response. Max value allowed - 1000. Default is 500, if got null.

RESOURCE_ID
string
Example: RESOURCE_ID=vm-12345678

Filter log extracted entries related to a specific resource id Default: Null

SEVERITY
string
Enum: "DEBUG" "WARN" "INFO" "ALL" "ERROR"
Example: SEVERITY=WARN

Severity of log entries to extract.

toDate
required
string
Example: toDate=2020-09-01 or fromDate=1598918400000

Get items on or before this date (ISO 8601 or Unix timestamp)

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Elastigroup Azure Stateful

Elastigroup for Microsoft Azure Stateful Node

Elastigroup Concepts and Tutorials

Create Stateful Node

Create a new stateful node.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
object (Azure Stateful Node)
required
object (Stateful Node Compute)

Defines the computational parameters to use when launch the VM for the Stateful Node.

description
string

The description for the Stateful Node.

object (Stateful Node Health)

Set health check and auto-healing of unhealthy VMs.

object (Stateful Node Integrations)

Configure integrations for the VMs in the stateful node.

name
required
string

Stateful Node Name.

required
object (Stateful Node Persistence)

Defines the persistence of the Stateful Node.

region
required
string

The Azure region in which the Stateful Node will be launched.

resourceGroupName
required
string

The Azure resource group in which the VM and all of the subsequent subresources will be launched.

object (Stateful Node Scheduling)

Scheduling settings for stateful node.

required
object (Stateful Node Strategy)

The strategy to launch the underlying VM and Spot’s behavior for the Stateful Node.

Responses

Request samples

Content type
application/json
{
  • "statefulNode": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get All Stateful Nodes

Get the configurations of all stateful nodes in a specific account.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

name
string
Example: name=MyStatefulGroup

Filters to find the stateful node via a specific name.

region
string
Example: region=eastus

Filters to find all the stateful nodes in a specific region.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Stateful Node

Get the configuration of an existing stateful node.

Authorizations:
auth
path Parameters
nodeId
required
string
Example: ssn-12345678

The ID of the stateful node.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Update Stateful Node

Update an existing stateful node.

Authorizations:
auth
path Parameters
nodeId
required
string
Example: ssn-12345678

The ID of the stateful node.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
object (Azure Stateful Node)
object (Stateful Node Compute)

Compute settings for Stateful Node

description
string

Describe your Azure Stateful Node

object (Stateful Node Health)

Set health check and auto-healing of unhealthy VMs.

object (Stateful Node Integrations)

Configure integrations for the stateful node VM.

name
string

Azure Stateful Node Name

object (Stateful Node Persistence)

Persistence settings for stateful node

object (Stateful Node Scheduling)

Scheduling settings for stateful node

object (Stateful Node Strategy)

Strategy for Stateful Node.

Responses

Request samples

Content type
application/json
{
  • "statefulNode": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Delete Stateful Node

Delete an existing stateful node from the account.

Authorizations:
auth
path Parameters
nodeId
required
string
Example: ssn-12345678

The ID of the stateful node.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
object (Delete Azure Stateful Node Configuration)
object (Disk Deallocation Config)

Disk Deallocation Configuration.

object (Network Deallocation Config)

Network Deallocation Configuration.

object (Public IP Deallocation Config)

Public IP Deallocation Configuration.

shouldDeregisterFromLb
boolean
Default: true

Indicates whether to deregister the stateful node's VM from any type of load balancer. Can be changed to false only when shouldTerminateVms is 'false'

shouldRevertToOd
boolean
Default: false

Indicates whether to change the stateful node's VM lifecycle to on-demand. Can be changed to true only when shouldTerminateVms is 'false'.

shouldTerminateVm
required
boolean

Indicates whether to delete the stateful node's VM.

object (Snapshot Deallocation Config)

Snapshot Deallocation Configuration.

Responses

Request samples

Content type
application/json
{
  • "deallocationConfig": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Stateful Node Resources

Get the node's attached resources (storage and network interfaces).

Authorizations:
auth
path Parameters
nodeId
required
string
Example: ssn-12345678

The ID of the stateful node.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Stateful Node Status

Get the status of a specific stateful node.

Authorizations:
auth
path Parameters
nodeId
required
string
Example: ssn-12345678

The ID of the stateful node.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get All Stateful Node Statuses

Get the statuses of all stateful nodes in a specific account.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Update Stateful Node State

Update the stateful node state.

Authorizations:
auth
path Parameters
nodeId
required
string
Example: ssn-12345678

The ID of the stateful node.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
state
string (Stateful Node State Change)
Enum: "pause" "resume" "recycle"

Responses

Request samples

Content type
application/json
{
  • "state": "pause"
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Stateful Node from an Azure VM

Get the configuration of a stateful node that was built from an Azure VM. This configuration is used for the Import VM to a Stateful Node API.

Authorizations:
auth
path Parameters
resourceGroupName
required
string
Example: importResourceGroup

Name of the Resource Group of the imported VM.

virtualMachineName
required
string
Example: spot-12345678-vm

Name of the imported VM.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Import VM to a Stateful Node

Import an Azure VM and create a stateful node by providing a node configuration.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
object (Azure Import Stateful Node)
convertUnmanagedDisks
boolean
Default: false

Converts virtual machine unmanaged disks to managed disks.

drainingTimeout
integer [ 0 .. 1800 ]
Default: 120

Time in seconds before shutdown incase of load balancing.

object (Azure Stateful Node)
originalVmName
required
string

Azure Import Stateful Node Name

resourceGroupName
required
string

Name of the Resource Group for Stateful Node.

resourcesRetentionTime
integer [ 0 .. 731 ]
Default: 96

Time in hours to delete the original resources after the import has finished.

Responses

Request samples

Content type
application/json
{
  • "statefulNodeImport": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Stateful Node Import Status

Get the import process status of a stateful node.

Authorizations:
auth
path Parameters
importId
required
string
Example: sin-12345678

Import Id.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Swap OS Disk to Stateful Node

Configure a new managed OS disk for an OS persisted paused/stopped Stateful Node.

Authorizations:
auth
path Parameters
nodeId
required
string
Example: ssn-12345678

The ID of the stateful node.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
osDiskName
required
string

Specify the name of the new OS disk.

osDiskResourceGroupName
required
string

The resource group name in which the new OS disk exists.

retentionTime
integer >= 0

Time to keep the original OS disk before deletion (hours).

shouldTerminate
boolean
Default: true

Indicates whether to delete the original OS disk.

Responses

Request samples

Content type
application/json
{
  • "osDiskName": "OsDisk",
  • "osDiskResourceGroupName": "MyResourceGroup",
  • "shouldTerminate": false,
  • "retentionTime": 1
}

Attach Data Disk to Stateful Node

Create a new data disk and attaches it to the stateful node.

Authorizations:
auth
path Parameters
nodeId
required
string
Example: ssn-12345678

The ID of the stateful node.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
caching
string
Enum: "None" "ReadOnly" "ReadWrite"

Specifies the host caching requirements. With disk caching enabled, VMs can achieve higher levels of performance.

  • If not specified, the Azure default behavior will be applied.
dataDiskName
required
string

The name of the created data disk.

dataDiskResourceGroupName
required
string

The resource group name in which the data disk will be created.

lun
integer
Default: "ordinal"

The LUN of the data disk. If not defined, the LUN will be set in order.

sizeGB
required
integer [ 1 .. 1023 ]

The size of the data disk in GB, Required if dataDisks is specified.

storageAccountType
required
string
Enum: "Standard_LRS" "Premium_LRS" "StandardSSD_LRS" "UltraSSD_LRS" "StandardSSD_ZRS" "Premium_ZRS" "PremiumV2_LRS"

The type of the data disk.

zone
string
Enum: "1" "2" "3"

The Availability Zone in which the data disk will be created. If not defined, the data disk will be created regionally.

Responses

Request samples

Content type
application/json
{
  • "dataDiskName": "MyDisk",
  • "dataDiskResourceGroupName": "dataDiskResourceGroup",
  • "sizeGB": 1,
  • "lun": 1,
  • "storageAccountType": "Standard_LRS",
  • "zone": "1",
  • "caching": "ReadOnly"
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Detach Data Disk From Stateful Node

Detach a data disk from a stateful node.

Authorizations:
auth
path Parameters
nodeId
required
string
Example: ssn-12345678

The ID of the stateful node.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
dataDiskName
required
string

The name of the created data disk.

dataDiskResourceGroupName
required
string

The resource group name in which the data disk exists.

shouldDeallocate
required
boolean

Indicates whether to delete the data disk in addition to detach.

ttlInHours
integer
Default: 0

Hours to keep the disk alive before deletion.

Responses

Request samples

Content type
application/json
{
  • "dataDiskName": "MyDisk",
  • "dataDiskResourceGroupName": "dataDiskResourceGroup",
  • "shouldDeallocate": true,
  • "ttlInHours": 1
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Stateful Node Logs

Get the logs of a stateful node according to severity and time period filter parameters.

Authorizations:
auth
path Parameters
nodeId
required
string
Example: ssn-12345678

The ID of the stateful node.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

fromDate
required
string
Example: fromDate=2020-09-01 or fromDate=1598918400000

Get items on or after this date (ISO 8601 or Unix timestamp)

limit
integer [ 0 .. 1000 ]
Default: 500
Example: limit=100

Maximum number of lines to extract in a response.

resourceId
string
Default: null
Example: resourceId=ssn-12345678

Filter log extracted entires related to a specific resource id

severity
string
Enum: "DEBUG" "WARN" "INFO" "ALL" "ERROR"
Example: severity=WARN

Severity of log entries to extract.

toDate
required
string
Example: toDate=2020-09-01 or fromDate=1598918400000

Get items on or before this date (ISO 8601 or Unix timestamp)

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get All Stateful Node Costs

Get the total costs of a single stateful node/all stateful nodes and for a specific time period.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

fromDate
required
string
Example: fromDate=2020-09-01 or fromDate=1598918400000

Get items on or after this date (ISO 8601 or Unix timestamp)

ownerId
string
Example: ownerId=ssn-12345678

Aggregates costs and usage by stateful node.

toDate
required
string
Example: toDate=2020-09-01 or fromDate=1598918400000

Get items on or before this date (ISO 8601 or Unix timestamp)

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get All Stateful Node Aggregated Daily Costs

Get the total costs per day of a single stateful node/all stateful nodes and for a specific time period.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

fromDate
required
string
Example: fromDate=2020-09-01 or fromDate=1598918400000

Get items on or after this date (ISO 8601 or Unix timestamp)

ownerId
string
Example: ownerId=ssn-12345678

Aggregates costs and usage daily by stateful node.

toDate
required
string
Example: toDate=2020-09-01 or fromDate=1598918400000

Get items on or before this date (ISO 8601 or Unix timestamp)

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Stateful Node Size Usage

Get the daily costs per VM size of a single stateful node/all stateful nodes and for a specific time period.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

fromDate
required
string
Example: fromDate=2020-09-01 or fromDate=1598918400000

Get items on or after this date (ISO 8601 or Unix timestamp)

ownerId
string
Example: ownerId=ssn-12345678

Aggregates VM size usage daily by stateful node.

toDate
required
string
Example: toDate=2020-09-01 or fromDate=1598918400000

Get items on or before this date (ISO 8601 or Unix timestamp)

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Stateful Node AWS

Stateful Node is a Spot solution for launching and managing a single compute instance. On the AWS cloud, for a standard single instance workload, an On-Demand EC2 instance is launched. The instance is expected to be highly available, easily manageable, and integrate well with additional services and monitoring tools. For more information please review the concepts section.

Stateful Node for AWS Concepts and Tutorials

Create Stateful Node

Create a new Stateful Node resource.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
object
object (MI Compute)
description
string

Describe your Stateful Node resource

object
object (MI integrations)
name
required
string

Stateful Node name

object

Persistence settings. Should omit at least one of the persist options below.

region
required
string

The AWS region your resource will be created in.

object (MI Scheduling)
object (MI Strategy)

Responses

Request samples

Content type
application/json
{
  • "managedInstance": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

List Stateful Nodes

List all Stateful Node resources in the account.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Update Stateful Node

  • Update one or more attributes in your Stateful Node.
  • This API supports partial updates, so only specific fields can be updated separately.
  • In order to remove a setting from the instance config, set the object value to null.
  • For a Full List of the Elastigroup JSON object reference please see Stateful Node Create.
Authorizations:
auth
path Parameters
MI_ID
required
string
Example: smi-111

Stateful Node ID you want to get

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
object
object (MI Compute)
description
string

Describe your Stateful Node resource

object
object (MI integrations)
name
required
string

Stateful Node name

object

Persistence settings. Should omit at least one of the persist options below.

region
required
string

The AWS region your resource will be created in.

object (MI Scheduling)
object (MI Strategy)

Responses

Request samples

Content type
application/json
{
  • "managedInstance": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Stateful Node

Get specific Stateful Node config.

Authorizations:
auth
path Parameters
MI_ID
required
string
Example: smi-111

Stateful Node ID you want to get

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Delete Stateful Node

Get specific Stateful Node config.

Authorizations:
auth
path Parameters
MI_ID
required
string
Example: smi-111

Stateful Node ID you want to get

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
object
object

Responses

Request samples

Content type
application/json
{
  • "deallocationConfig": {
    },
  • "amiBackup": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Pause Stateful Node

Pause an existing Stateful Node.

Authorizations:
auth
path Parameters
MI_ID
required
string
Example: smi-111

Stateful Node ID you want to get

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Resume Stateful Node

Resume an existing Stateful Node.

Authorizations:
auth
path Parameters
MI_ID
required
string
Example: smi-111

Stateful Node ID you want to get

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Recycle Stateful Node

Recycle an existing Stateful Node.

Authorizations:
auth
path Parameters
MI_ID
required
string
Example: smi-111

Stateful Node ID you want to get

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Stateful Node Costs

Get financial information on a specific Stateful Node. To use this API, managedInstanceId must be defined.

Authorizations:
auth
path Parameters
MI_ID
required
string
Example: smi-111

Stateful Node ID you want to get

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

aggregationPeriod
string

Data values following either a date format (YYYY-MM-DDTHH:mm:ss.SSSZ ; 2016-01-10T00:00:00.000Z) or Unix seconds Timestamp (1494751821)

fromDate
required
string <date-time>
Example: fromDate=2019-05-17

Get items on or after this date (ISO 8601)

toDate
required
string <date-time>
Example: toDate=2019-05-25

Get items on or before this date (ISO 8601)

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Stateful Node Status

Describes the current status of a specific Stateful Node – entailing information regarding running instance and its status.

Authorizations:
auth
path Parameters
MI_ID
required
string
Example: smi-111

Stateful Node ID you want to get

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Delete Volume in a Stateful Node

Delete a Volume that is part of a Stateful Node

Authorizations:
auth
path Parameters
MI_ID
required
string
Example: smi-123456

Stateful Node ID

volumeId
required
string
Example: vol-0faa4b2957a3d59c8

Volume ID

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Import Instance from AWS

  • Import an instance from AWS into Stateful Node, while keeping the instance data and its persistence settings.
  • This call is starting the migration and returns migration ID.
  • In order to get migration status use the Get Migration Status call
Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
required
object (Migration)

Migration Configuration

Array of objects (Availability Zones)

List of availability zones for the Stateful Node. Should exist only if shouldKeepPrivateIp is false.

managedInstanceName
string

Set Stateful Node name

originalInstanceId
required
string

The instance ID on AWS

product
string

Set instance's product

region
required
string

Set instance's region

shouldKeepMetadataOptions
boolean

Set whether the instance should keep its metadataOptions or not

shouldKeepPrivateIp
boolean

Set whether the instance should keep its private ip or not

shouldTerminateInstance
boolean

Set true or false whether to terminate the instance in AWS. Note: If shouldKeepPrivateIp is true, then shouldTerminateInstance must be true. Otherwise an error will be returned.

spotInstanceTypes
Array of strings

List of possible instance types for the Stateful Node

Responses

Request samples

Content type
application/json
{
  • "migration": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Import Multiple Instances from AWS

  • Import multiple stateful instances from AWS into Stateful Node, preserving both instance data and persistence settings.
  • This call initiates migration for all instances and returns the associated migration IDs.
  • To check the status of multiple migrations, use the `Get Multiple Instance Migration Status` call.
  • Note: The response contains a `failures` field. In the event that one or more instances failed to migrate, this field will provide the corresponding resource IDs and error messages. If all migrations were successful, this field will return an empty list.
Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
required
Array of objects (Migrations)

List of Migration requests

Array
Array of objects (Availability Zones)

List of availability zones for the Stateful Node. Should exist only if shouldKeepPrivateIp is false.

managedInstanceName
string

Set Stateful Node name

originalInstanceId
required
string

The instance ID on AWS

product
string

Set instance's product

region
required
string

Set instance's region

shouldKeepMetadataOptions
boolean

Set whether the instance should keep its metadataOptions or not

shouldKeepPrivateIp
boolean

Set whether the instance should keep its private ip or not

shouldTerminateInstance
boolean

Set true or false whether to terminate the instance in AWS. Note: If shouldKeepPrivateIp is true, then shouldTerminateInstance must be true. Otherwise an error will be returned.

spotInstanceTypes
Array of strings

List of possible instance types for the Stateful Node

Responses

Request samples

Content type
application/json
{
  • "migrations": [
    ]
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Instance Migration Status

  • Get a previously initiated instance migration status.
  • To initiate an instance migration from AWS use the Import Instance From AWS call.
  • On initiation, the migration would be in the following state: `MIGRATE_START`.
  • Possible end states for the migration are: `MIGRATE_CANCEL`, `MIGRATE_FINISH`, `MIGRATE_ERROR`.
Authorizations:
auth
path Parameters
MIGRATION_ID
required
string
Example: smg-123

Migration ID for which you want to get the status

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Multiple Instance Migration Status

  • Retrieve the status of a previously initiated multiple instance migrations.
  • To initiate multiple instance migrations from AWS, use the `Import Multiple Instances From AWS` call.
  • Upon initiation, the migration will be in the state of `MIGRATE_START`.
  • Possible final states for each migration include `MIGRATE_CANCEL`, `MIGRATE_FINISH`, and `MIGRATE_ERROR`.
Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
migrationIds
required
Array of strings (Migration Ids)

List of Migration ids. Use the migrationId field received in a Import Multiple Instances from AWS response

Responses

Request samples

Content type
application/json
{
  • "migrationIds": [
    ]
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Update Stateful Node States

Update the state of multiple Stateful Nodes.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
required
Array of objects (Stateful Node State)

An array of Stateful Node State objects (must contain at least 1 object).

Array
id
required
string

Identifier of the Stateful Node.

state
required
string
Enum: "PAUSE" "RESUME"

The new state of the Stateful Node.

Responses

Request samples

Content type
application/json
{
  • "managedInstanceStates": [
    ]
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

List Audit Log Events

Gets audit events that have response status of 200. This is the default when the responseStatus parameter is not included in the query. When you use responseStatus in the query, you can get all audit events without regard to status.

The API requires one of the following permissions to be defined in Spot:

  • Permission: Organization Viewer (See User Roles) or
  • Action: setup:describeAllAuditEvents (See Access Policies)
Authorizations:
auth
query Parameters
accountId
string
Example: accountId=act-123abc

ID of the account associated with your token

fromDate
required
string <string>
Example: fromDate=1598918400000

Get items on or after this date (Unix timestamp)

responseStatus
string
Example: responseStatus=all

Determines whether the audit events should be filtered by their response status code or not. Valid values: "success": Gets only events with status 200. "all": Audit events will not be filtered by response status codes, and all the events will be returned. Default: success

toDate
required
string <string>
Example: toDate=1598918400000

Get items on or before this date (Unix timestamp)

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Create Health Check

Create an HCS for Spot Elastigroup.

Authorizations:
auth
query Parameters
accountId
string
Example: accountId=act-123abc

ID of the account associated with your token

Request Body schema: application/json
required
object

Group

object
name
string

A logical name for the health check

proxyAddress
required
string

The public hostname / IP where you installed the Spot HCS

proxyPort
integer

The port of the HCS. Default: 80

resourceId
required
string

Spot Resource ID

Responses

Request samples

Content type
application/json
{
  • "healthCheck": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

List Health Checks

Get a list of all HCS services.

Authorizations:
auth
query Parameters
accountId
string
Example: accountId=act-123abc

ID of the account associated with your token

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Update Health Check

Update existing HCS.

Authorizations:
auth
path Parameters
HEALTHCHECK_ID
required
string
Example: hcs-123

The HCS you want to update

query Parameters
accountId
string
Example: accountId=act-123abc

ID of the account associated with your token

Request Body schema: application/json
required
object

Group

object
name
string

A logical name for the health check

proxyAddress
string

The public hostname / IP where you installed the Spot HCS

proxyPort
integer

The port of the HCS. Default: 80

Responses

Request samples

Content type
application/json
{
  • "healthCheck": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Health Check

List the information of a particular HCS

Authorizations:
auth
path Parameters
HEALTHCHECK_ID
required
string
Example: hcs-123

The HCS you want to update

query Parameters
accountId
string
Example: accountId=act-123abc

ID of the account associated with your token

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Delete Health Check

Delete existing HCS

Authorizations:
auth
path Parameters
HEALTHCHECK_ID
required
string
Example: hcs-123

The HCS you want to update

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Notifications Service

A Spot Notifications service enables you a fast, flexible, fully managed push notification service that lets you know about major events that happened in your Spot account.ֿ Spot Notifications makes it simple and cost-effective to get push notifications to your email address, HTTP, HTTPS or AWS SNS (Simple Notifications Service).

Update Account Notification Policy

Update the account notification policy

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
object
object
object

Responses

Request samples

Content type
application/json
{
  • "accountPolicy": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Account Notification Policy

Get the account notification policy

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Subscribe

Create a notification for your resources

Authorizations:
auth
query Parameters
accountId
string
Example: accountId=act-123abc

ID of the account associated with your token

Request Body schema: application/json
One of
required
object

Object defining the subscription parameters

endpoint
required
string

The endpoint the notification will be sent to. url in case of http/https/web, email address in case of email/email-json and sns-topic-arn in case of aws-sns. For example: YOUR@EMAIL.COM or https://YOUR_ENDPOINT.COM or SNS_TOPIC_ARN

object

The format of the notification content (JSON Format: Key + Value). The keys can be renamed.

eventType
required
string
Enum: "AWS_EC2_INSTANCE_TERMINATE" "AWS_EC2_INSTANCE_TERMINATED" "AWS_EC2_INSTANCE_LAUNCH" "AWS_EC2_INSTANCE_READY_SIGNAL_TIMEOUT" "SIGNAL_TIMEOUT_SHUTDOWN_SCRIPT" "AWS_EC2_CANT_SPIN_OD" "AWS_EC2_INSTANCE_UNHEALTHY_IN_ELB" "GROUP_ROLL_FAILED" "GROUP_ROLL_FINISHED" "CANT_SCALE_UP_GROUP_MAX_CAPACITY" "GROUP_UPDATED" "AWS_EMR_PROVISION_TIMEOUT" "GROUP_BEANSTALK_INIT_READY" "AZURE_VM_TERMINATED" "AZURE_VM_TERMINATE" "AWS_EC2_MANAGED_INSTANCE_PAUSING" "AWS_EC2_MANAGED_INSTANCE_RESUMING" "AWS_EC2_MANAGED_INSTANCE_RECYCLING" "AWS_EC2_MANAGED_INSTANCE_DELETING"

The event to send the notification when triggered.

protocol
required
string
Enum: "aws-sns" "email" "email-json" "web"

The protocol to send the notification.

The following values are deprecated: http https You can use the generic web protocol instead. aws-sns is only supported with AWS provider

resourceId
required
string

Spot Resource ID (Elastigroup ID, Ocean ID or Stateful Node ID)

Responses

Request samples

Content type
application/json
Example
{
  • "subscription": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

List Subscriptions

List all subscriptions and their information

Authorizations:
auth
query Parameters
accountId
string
Example: accountId=act-123abc

ID of the account associated with your token

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Unsubscribe

Delete an existing page

Authorizations:
auth
path Parameters
subscriptionId
required
string
Example: sis-1234abcd

The subscription ID to operate on.

query Parameters
accountId
string
Example: accountId=act-123abc

ID of the account associated with your token

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Subscription

Get a specific notification and its information

Authorizations:
auth
path Parameters
subscriptionId
required
string
Example: sis-1234abcd

The subscription ID to operate on.

query Parameters
accountId
string
Example: accountId=act-123abc

ID of the account associated with your token

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Update Subscription

Update existing notification

Authorizations:
auth
path Parameters
subscriptionId
required
string
Example: sis-1234abcd

The subscription ID to operate on.

query Parameters
accountId
string
Example: accountId=act-123abc

ID of the account associated with your token

Request Body schema: application/json
required
object

Element that store all the subscription config

endpoint
string

The endpoint the notification will be sent to. url in case of http/https/web, email address in case of email/email-json and sns-topic-arn in case of aws-sns

Responses

Request samples

Content type
application/json
{
  • "subscription": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Insights Service

Potential Savings

Describe Potential Savings for AWS resources like - ASG (Auto-scaling groups), Beanstalk, ELB, ECS, EMR and tagged instances. The response will provide Potential monthly savings in USD

Authorizations:
auth
query Parameters
accountId
string
Example: accountId=act-123456789

ID of the account associated with your token

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Instances Potential Savings

Describe potential savings for the listed instances. You can provide multiple instance IDs separated by a comma. The response will provide potential monthly savings in USD.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

instanceIds
required
string
Example: instanceIds=i-1234567

The instance ID

region
required
string
Example: region=us-east-1

The AWS Region

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Costs per Account

Retrieve costs up to one year back per specified account over a specified time period.

Authorizations:
auth
query Parameters
accountId
string
Example: accountId=act-123456789

ID of the account associated with your token

aggregationPeriod
string
Example: aggregationPeriod=daily

Optional. The time period over which data is aggregated. Can only be "daily". For example, the figures in each data set are per day

fromDate
string
Example: fromDate=2018-06-20

Date can be either in ISO-8601 date format (yyyy-mm-dd) or in Unix Timestamp format (e.g. 1494751821472). *Minimum from date can be one year ago.

toDate
string
Example: toDate=2018-11-20

Date can be either in ISO-8601 date format (yyyy-mm-dd) or in Unix Timestamp format (e.g. 1494751821472). *Data is shown until the past day (Does not include today's costs)

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Suggested Instance Type

Get suggested instance types by required resources. Note that request must include region, and at least one of the following values - baselineInstanceType, requiredVCpu, requiredMemoryGib

Authorizations:
auth
query Parameters
accountId
string
Example: accountId=act-123abc

ID of the account associated with your token

Request Body schema: application/json
object (AWS Elastigroup)
baselineInstanceType
string

Set valid AWS instance type as baseline

region
string

Set valid AWS region

object

Set required Memory (in Gib) resources by min / max

object

Set required CPU resources by min / max

Responses

Request samples

Content type
application/json
{
  • "requirements": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Create Data Integration

Create a new data integration, an object representing a connection to a third-party vendor to export to and import data from.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
object
required
S3 (object) or Azure Blob (object)

The config of this data integration. Depends on the value of vendor.

name
required
string

The name of the data integration.

vendor
required
string
Enum: "s3" "azureBlob"

The vendor for the data integration. This value affects the expected config.

Responses

Request samples

Content type
application/json
{
  • "dataIntegration": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

List Data Integration

List data integrations.

Authorizations:
auth
query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

health
string
Enum: "valid" "invalid" "forbidden"
Example: health=valid

The health status of the data integrations to list.

name
string
Example: name=my-data-integration

The name of the data integrations to list.

status
string
Enum: "enabled" "disabled"
Example: status=enabled

The status of the data integrations to list.

vendor
string
Enum: "s3" "azureBlob"
Example: vendor=s3

The vendor of the data integrations to list.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Update Data Integration

Update an existing data integration.

Authorizations:
auth
path Parameters
dataIntegrationId
required
string
Example: di-123abc

Identifier of the data integration.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Request Body schema: application/json
object
S3 (object) or Azure Blob (object)

The config of this data integration. Depends on the value of vendor.

name
string

The name of the data integration.

status
string
Enum: "enabled" "disabled"

Determines if this data integration is on or off.

vendor
required
string
Enum: "s3" "azureBlob"

The vendor for the data integration. This value affects the expected config. This value is immutable and must be the same as the existing data integration.

Responses

Request samples

Content type
application/json
{
  • "dataIntegration": {
    }
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Data Integration

Get an existing data integration.

Authorizations:
auth
path Parameters
dataIntegrationId
required
string
Example: di-123abc

Identifier of the data integration.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Delete Data Integration

Delete an existing data integration.

Authorizations:
auth
path Parameters
dataIntegrationId
required
string
Example: di-123abc

Identifier of the data integration.

query Parameters
accountId
required
string
Example: accountId=act-123456789

The ID of the account associated with your token.

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Get Organization Savings

Get the savings of the organization between the input time range.

Authorizations:
auth
query Parameters
fromDate
string
Example: fromDate=2022-06-20

Date can be either in ISO-8601 date format (yyyy-mm-dd) or in Unix Timestamp format (e.g. 1494751821472). *Minimum from date can be one year ago.

toDate
string
Example: toDate=2022-11-20

Date can be either in ISO-8601 date format (yyyy-mm-dd) or in Unix Timestamp format (e.g. 1494751821472). *Data is shown until the past day (Does not include today's costs)

Responses

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Connect Executions

Get Execution

Get details for the selected workflow execution.

Authorizations:
auth
path Parameters
exe_id
required
string

unique execution id

Responses

Response samples

Content type
application/json
{
  • "AutomationExecutionId": "string",
  • "AutomationExecutionStatus": "string",
  • "DocumentName": "string",
  • "DocumentVersion": 0,
  • "ExecutedBy": "string",
  • "ExecutionEndTime": "2019-08-24T14:15:22Z",
  • "ExecutionStartTime": "2019-08-24T14:15:22Z",
  • "Mode": "string",
  • "Outputs": { },
  • "Parameters": { },
  • "PostProcessingCompletedAt": "2019-08-24T14:15:22Z",
  • "ResolvedTargets": { },
  • "StepExecutions": [
    ],
  • "Targets": [
    ],
  • "TaskId": 0,
  • "TenantId": "string",
  • "Trigger": "string",
  • "WorkflowDeleted": true,
  • "WorkspaceId": "string"
}

Get Execution download url

Get link to download details for the selected workflow execution.

Authorizations:
auth
path Parameters
exe_id
required
string

unique execution id

Responses

Response samples

Content type
application/json
{
  • "redirect_url": "string"
}

Start Execution

Start the execution of the selected workflow.

Authorizations:
auth
path Parameters
name
required
string

DisplayName of a workflow

query Parameters
version
string

Selected workflow version

workspace_id
string

Currently selected Workspace ID

Responses

Response samples

Content type
application/json
{
  • "exe_id": "string"
}

Connect Schedules

List Scheduled Workflows

List all scheduled workflows of the selected workspace.

Authorizations:
auth
query Parameters
task_id
string

(optional) filter related schedules to a task

workspace_id
string

currently selected Workspace ID

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Delete Schedule

Delete a selected execution schedule of the selected workflow.

Authorizations:
auth
path Parameters
workflow_name
required
string

unique workflow name only

query Parameters
version
string

version of workflow in schedule

workspace_id
string

currently selected Workspace ID

Responses

List Schedules for Workflow

List all execution schedules for the selected workflow.

Authorizations:
auth
path Parameters
workflow_name
required
string

unique workflow name only

query Parameters
workspace_id
string

currently selected Workspace ID

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Create Schedule

Create a new execution schedule for the selected workflow.

Authorizations:
auth
path Parameters
workflow_name
required
string

unique workflow name only

query Parameters
workspace_id
string

currently selected Workspace ID

Request Body schema: application/json
expression
required
string

CRON expression of the schedule.

params
object

Runtime parameters for the workflow.

version
required
integer

Version of the workflow.

Responses

Request samples

Content type
application/json
{
  • "expression": "string",
  • "params": { },
  • "version": 0
}

Response samples

Content type
application/json
{
  • "rule_name": "string"
}

Update Schedule Status

Enable/disable the status of the selected execution schedule.

Authorizations:
auth
path Parameters
workflow_name
required
string

unique workflow name only

query Parameters
version
string

version of workflow in schedule

workspace_id
string

currently selected Workspace ID

Responses

Connect Settings

List API Keys

Endpoint to fetch list of API Keys and its values.

Authorizations:
auth
query Parameters
disable_redact
string

Disable redacting API keys

workspace_id
string

Currently selected Workspace ID

Responses

Response samples

Content type
application/json
{
  • "body": {
    },
  • "statusCode": 0
}

Delete API Key

Endpoint to delete an API Key.

Authorizations:
auth
path Parameters
apikey_name
required
string

API key name

query Parameters
workspace_id
string

Currently selected Workspace ID

Responses

Response samples

Content type
application/json
{
  • "body": {
    },
  • "statusCode": 0
}

Get API Key

Endpoint to fetch the selected API key's information from the selected workspace.

Authorizations:
auth
path Parameters
apikey_name
required
string

API key name

query Parameters
disable_redact
string

Disable redacting API keys

workspace_id
string

Currently selected Workspace ID

Responses

Response samples

Content type
application/json
{
  • "body": {
    },
  • "statusCode": 0
}

Create API Key

Endpoint to create a new API Key.

Authorizations:
auth
path Parameters
apikey_name
required
string

API key name

query Parameters
workspace_id
string

Currently selected Workspace ID

Responses

Response samples

Content type
application/json
{
  • "body": {
    },
  • "statusCode": 0
}

Update API Key

Move the API key to the new workspace.

Authorizations:
auth
path Parameters
apikey_name
required
string

API key name

query Parameters
workspace_id
string

Currently selected Workspace ID

Responses

Response samples

Content type
application/json
{
  • "body": {
    },
  • "statusCode": 0
}

Get Alias Name Availability

Checks whether given Alias name is available for use for the selected service in the current organization.

Authorizations:
auth
path Parameters
service
required
string

Name of connector service (value=ansible|apikeys|bitbucket|datadog|git|humio|instana|jira|opsgenie|aws_health|pagerduty|prometheus|pulumi|slack|splunk|splunk_on_call|spot|squadcast|terraform|terraform_cli|twilio|zoom)

Request Body schema: application/json
alias
required
string

The alias to check availability for.

Responses

Request samples

Content type
application/json
{
  • "alias": "string"
}

Response samples

Content type
application/json
{
  • "body": {
    },
  • "statusCode": 0
}

List Enabled Connectors

Retrieve a list of all enabled connectors (integration or resource), excluding those that are exclusively trigger-based. For each connector, extract essential settings from its schema and determine a boolean status indicating whether it's configured or not.

Authorizations:
auth
query Parameters
workspace_id
string

Currently selected Workspace ID

Responses

Response samples

Content type
application/json
{
  • "body": {
    },
  • "statusCode": 0
}

Authenticate Jira Integration

API for status of Jira OAuth approval by Customer (Jira administrator).

Authorizations:
auth
query Parameters
alias
string

Slack integration alias.

jira_url
string

URL of the Jira instance.

req_token
string

The request token provided by Jira for the integration.

req_token_secret
string

The request token secret provided by Jira for the integration.

workspace_id
string

Currently selected Workspace ID

Responses

Response samples

Content type
application/json
{
  • "body": {
    },
  • "statusCode": 0
}

Get Jira Authorization URL

This API is used to fetch Jira authorization URL.

Authorizations:
auth
query Parameters
alias
string

Slack integration alias.

jira_url
string

URL of the Jira instance.

Responses

Response samples

Content type
application/json
{
  • "body": {
    },
  • "statusCode": 0
}

Get Spot Connect Plans

Fetch various Spot Connect plan details with quotas and pricing.

Authorizations:
auth

Responses

Response samples

Content type
application/json
{
  • "body": {
    },
  • "statusCode": 0
}

List Public IPs

Returns a list of public IPs for customers to whitelist.

Authorizations:
auth

Responses

Response samples

Content type
application/json
{
  • "body": {
    },
  • "statusCode": 0
}

Get Quotas

Fetch quotas for organization and provide information on their limits and current status.

Authorizations:
auth

Responses

Response samples

Content type
application/json
{
  • "body": {
    },
  • "statusCode": 0
}

Get Schema

Get the JSON schema for the given integration or resource.

Authorizations:
auth
path Parameters
service
required
string

Name of connector service (value=ansible|apikeys|bitbucket|datadog|git|humio|instana|jira|opsgenie|aws_health|pagerduty|prometheus|pulumi|slack|splunk|splunk_on_call|spot|squadcast|terraform|terraform_cli|twilio|zoom)

Responses

Response samples

Content type
application/json
{
  • "body": {
    },
  • "statusCode": 0
}

Authenticate Slack Integration

After the user installs/authorizes the Spot Connect Slack app in their workspace, they will be redirected back to the Slack integration page in the Fylamynt web app with an authorization code. The web app will then call this API endpoint with that 'code' in the query parameter. Instead, if the user rejects to authorize the Fylamynt Slack app in their workspace, the API request from the web app will contain the 'error' code (e.g., error=access_denied) returned from Slack. The following code processes the request and returns success or failure response to the web app. Slack instance alias is part of 'state' query parameter, previously 'state' query parameter contained subdomain.

Authorizations:
auth
query Parameters
code
string

Slack authorization code. Provide either code or an error message, but not both.

error
string

Error message. Provide either code or an error message, but not both.

state
required
string

Alias of the Slack integration

workspace_id
string

Currently selected Workspace ID

Responses

Response samples

Content type
application/json
{
  • "body": {
    },
  • "statusCode": 0
}

Get Slack Integration URL

This API is used to retrieve the Slack integration URL. The integration_id URI parameter is optional for this API.

Authorizations:
auth
query Parameters
alias
string

Slack integration alias.

Responses

Response samples

Content type
application/json
{
  • "body": {
    },
  • "statusCode": 0
}

List Trigger Connectors

Endpoint to fetch the list of trigger connectors each containing the name, display name, snippet name, and configuration status of the respective connector.

Authorizations:
auth

Responses

Response samples

Content type
application/json
{
  • "body": {
    },
  • "statusCode": 0
}

The Fylamynt web app will make a POST request to this endpoint that contains an

authorization code in the query parameter. Once we receive this request, we will use the auth code and exchange it for an OAuth token with a request type 'authorization_code' by calling back to Zoom. If we successfully exchange the auth code for a token, we will then save the returned 'refresh_token' to secrets manager.

Authorizations:
auth

Responses

This API is used for fetching the Zoom app integration URL

Authorizations:
auth

Responses

List Integration Instances

Get the list of instances for a given service.

Authorizations:
auth
path Parameters
service
required
string

Name of connector service (value=ansible|apikeys|bitbucket|datadog|git|humio|instana|jira|opsgenie|aws_health|pagerduty|prometheus|pulumi|slack|splunk|splunk_on_call|spot|squadcast|terraform|terraform_cli|twilio|zoom)

query Parameters
disable_redact
string

Disable redacting API keys

workspace_id
string

Currently selected Workspace ID

Responses

Response samples

Content type
application/json
{
  • "body": [
    ],
  • "statusCode": 0
}

Create Secret

Create a new secret for a given service.

The Example model contains models for all services that can be created. When calling this endpoint for a specific service, only the credentials for that service should be provided in the payload.

The payload should be structured with the credentials inside a 'credentials' key. For example, for an S3 integration:

{ "credentials": { "alias": "my-s3-integration", "target": "my-target", "name": "my-bucket-name" } }

Not all fields from all_input_models need to be sent in the payload, only those relevant to the specific service being created.

Response will be the instance credentials that was created.

Authorizations:
auth
path Parameters
service
required
string

Name of connector service (value=ansible|apikeys|bitbucket|datadog|git|humio|instana|jira|opsgenie|aws_health|pagerduty|prometheus|pulumi|slack|splunk|splunk_on_call|spot|squadcast|terraform|terraform_cli|twilio|zoom)

query Parameters
workspace_id
string

Currently selected Workspace ID

Request Body schema: application/json
object (AnsibleCredentials)
object (Azure_openaiCredentials)
object (BitbucketCredentials)
object (CloudformationCredentials)
object (DatadogCredentials)
object (EksCredentials)
object (ElasticsearchCredentials)
object (GitCredentials)
object (GkeCredentials)
object (HttpCredentials)
object (HumioCredentials)
object (JenkinsCredentials)
object (JiraCredentials)
object (New_relicCredentials)
object (PagerdutyCredentials)
object (PulumiCredentials)
object (S3Credentials)
object (ServicenowCredentials)
object (SlackCredentials)
object (SplunkCredentials)
object (Splunk_on_callCredentials)
object (SpotCredentials)
object (SshCredentials)
object (SumologicCredentials)
object (TerraformCredentials)
object (Terraform_cliCredentials)
object (TwilioCredentials)
object (ZendeskCredentials)

Responses

Request samples

Content type
application/json
{
  • "ansible": {
    },
  • "azure_openai": {
    },
  • "bitbucket": {
    },
  • "cloudformation": {
    },
  • "datadog": {
    },
  • "eks": {
    },
  • "elasticsearch": {
    },
  • "git": {
    },
  • "gke": {
    },
  • "http": {
    },
  • "humio": {
    },
  • "jenkins": {
    },
  • "jira": {
    },
  • "new_relic": {
    },
  • "pagerduty": {
    },
  • "pulumi": {
    },
  • "s3": {
    },
  • "servicenow": {
    },
  • "slack": {
    },
  • "splunk": {
    },
  • "splunk_on_call": {
    },
  • "spot": {
    },
  • "ssh": {
    },
  • "sumologic": {
    },
  • "terraform": {
    },
  • "terraform_cli": {
    },
  • "twilio": {
    },
  • "zendesk": {
    }
}

Response samples

Content type
application/json
{
  • "body": {
    },
  • "statusCode": 0
}

Delete Integration/Resource

Endpoint handling two use cases for removing connector integration or resource:

  1. For connectors storing secrets in the tenant secrets db, remove the dynamic secret keys added during connector integration
  2. For target account oriented resources stored in the Target Settings DB, remove the resource associated with one 'alias' account or all accounts
Authorizations:
auth
path Parameters
integration_id
required
string
service
required
string

Name of connector service (value=ansible|apikeys|bitbucket|datadog|git|humio|instana|jira|opsgenie|aws_health|pagerduty|prometheus|pulumi|slack|splunk|splunk_on_call|spot|squadcast|terraform|terraform_cli|twilio|zoom)

query Parameters
workspace_id
string

Currently selected Workspace ID

Responses

Response samples

Content type
application/json
{
  • "body": {
    },
  • "statusCode": 0
}

Get Integration/Resource

Get the details of the selected integration/resource instance.

Note: The JSON response will contain credentials specific to the selected service and integration, unlike the response model which shows all possible fields for all services. The model is provided to illustrate the complete set of fields that may be present in the response, depending on which service and integration is selected.

Authorizations:
auth
path Parameters
integration_id
required
string
service
required
string

Name of connector service (value=ansible|apikeys|bitbucket|datadog|git|humio|instana|jira|opsgenie|aws_health|pagerduty|prometheus|pulumi|slack|splunk|splunk_on_call|spot|squadcast|terraform|terraform_cli|twilio|zoom)

query Parameters
disable_redact
string

Disable redacting API keys

workspace_id
string

Currently selected Workspace ID

Responses

Response samples

Content type
application/json
{
  • "body": {
    },
  • "statusCode": 0
}

Set Default/Move Integration/Resource

An empty PATCH body "{}" will set the instance to default.

To move an individual instance: call this endpoint with the 'old' workspace_id as the query parameter and the 'new' workspace_id in the body.

E.X.: PATCH https:///settings//?workspace_id=cws-movefrom body: {"workspace_id": "cws-moveto"}

Authorizations:
auth
path Parameters
integration_id
required
string
service
required
string

Name of connector service (value=ansible|apikeys|bitbucket|datadog|git|humio|instana|jira|opsgenie|aws_health|pagerduty|prometheus|pulumi|slack|splunk|splunk_on_call|spot|squadcast|terraform|terraform_cli|twilio|zoom)

Request Body schema: application/json

Workspace ID of the workspace to move integration/resource to.

Schema not provided

Responses

Response samples

Content type
application/json
{
  • "body": {
    },
  • "statusCode": 0
}

Update Integration/Resource

Update the Integration/Resource secrets for a given service and given integration instance.

Note: The displayed request and response models show the structure for each service. When calling this endpoint, only the credentials for the specific service being updated should be provided in the payload under the 'credentials' key. The response will contain the newly updated integration information for that service.

For example, to update a Slack integration:

Request: { "credentials": { "alias": "updated-slack-integration", "bot_token": "xoxb-updated-token", "signing_secret": "updated-secret" } }

Response will contain the updated Slack integration details.

Authorizations:
auth
path Parameters
integration_id
required
string
service
required
string

Name of connector service (value=ansible|apikeys|bitbucket|datadog|git|humio|instana|jira|opsgenie|aws_health|pagerduty|prometheus|pulumi|slack|splunk|splunk_on_call|spot|squadcast|terraform|terraform_cli|twilio|zoom)

query Parameters
disable_redact
string

Disable redacting API keys

workspace_id
string

Currently selected Workspace ID

Request Body schema: application/json
object (AnsibleCredentials)
object (Azure_openaiCredentials)
object (BitbucketCredentials)
object (CloudformationCredentials)
object (DatadogCredentials)
object (EksCredentials)
object (ElasticsearchCredentials)
object (GitCredentials)
object (GkeCredentials)
object (HttpCredentials)
object (HumioCredentials)
object (JenkinsCredentials)
object (JiraCredentials)
object (New_relicCredentials)
object (PagerdutyCredentials)
object (PulumiCredentials)
object (S3Credentials)
object (ServicenowCredentials)
object (SlackCredentials)
object (SplunkCredentials)
object (Splunk_on_callCredentials)
object (SpotCredentials)
object (SshCredentials)
object (SumologicCredentials)
object (TerraformCredentials)
object (Terraform_cliCredentials)
object (TwilioCredentials)
object (ZendeskCredentials)

Responses

Request samples

Content type
application/json
{
  • "ansible": {
    },
  • "azure_openai": {
    },
  • "bitbucket": {
    },
  • "cloudformation": {
    },
  • "datadog": {
    },
  • "eks": {
    },
  • "elasticsearch": {
    },
  • "git": {
    },
  • "gke": {
    },
  • "http": {
    },
  • "humio": {
    },
  • "jenkins": {
    },
  • "jira": {
    },
  • "new_relic": {
    },
  • "pagerduty": {
    },
  • "pulumi": {
    },
  • "s3": {
    },
  • "servicenow": {
    },
  • "slack": {
    },
  • "splunk": {
    },
  • "splunk_on_call": {
    },
  • "spot": {
    },
  • "ssh": {
    },
  • "sumologic": {
    },
  • "terraform": {
    },
  • "terraform_cli": {
    },
  • "twilio": {
    },
  • "zendesk": {
    }
}

Response samples

Content type
application/json
{
  • "body": {
    },
  • "statusCode": 0
}

Connect Targets

Gets a list of all accounts

Authorizations:
auth
query Parameters
workspace_id
string

Currently selected Workspace ID

Responses

Creates a new entry in the database

Authorizations:
auth
query Parameters
workspace_id
string

Currently selected Workspace ID

Request Body schema: application/json
alias
required
string
external_id
required
string
is_default
required
boolean
preferred_region
required
string
role_arn
required
string

Responses

Request samples

Content type
application/json
{
  • "alias": "string",
  • "external_id": "string",
  • "is_default": true,
  • "preferred_region": "string",
  • "role_arn": "string"
}

Response samples

Content type
application/json
{
  • "alias": "string",
  • "external_id": "string",
  • "is_default": true,
  • "preferred_region": "string",
  • "role_arn": "string"
}

Only return the default entry

It's acceptable to have zero defaults, but more than one should be cleaned up. This can be done by updating an existing entry to set is_default=True.

Authorizations:
auth
query Parameters
workspace_id
string

Currently selected Workspace ID

Responses

delete the entry

Authorizations:
auth
path Parameters
target_alias
required
string

Unique alias for the target account

Responses

get all fields of a specific account

Authorizations:
auth
path Parameters
target_alias
required
string

Unique alias for the target account

Responses

Response samples

Content type
application/json
{
  • "alias": "string",
  • "external_id": "string",
  • "is_default": true,
  • "preferred_region": "string",
  • "role_arn": "string"
}

Update fields on an account

This will only change the updated fields and will leave all other fields in place.

Authorizations:
auth
path Parameters
target_alias
required
string

Unique alias for the target account

query Parameters
workspace_id
string

Currently selected Workspace ID

Request Body schema: application/json
alias
required
string
external_id
required
string
is_default
required
boolean
preferred_region
required
string
role_arn
required
string

Responses

Request samples

Content type
application/json
{
  • "alias": "string",
  • "external_id": "string",
  • "is_default": true,
  • "preferred_region": "string",
  • "role_arn": "string"
}

Response samples

Content type
application/json
{
  • "alias": "string",
  • "external_id": "string",
  • "is_default": true,
  • "preferred_region": "string",
  • "role_arn": "string"
}

Connect Workflows

Return all user workflows for a given workspace

Authorizations:
auth
query Parameters
owner
string

SSM document owner (value=Self|Amazon|All, default=All)

workspace_id
string

Currently selected Workspace ID

Responses

Create a new workflow in the selected workspace.

Authorizations:
auth
query Parameters
workspace_id
string

Currently selected Workspace ID

Request Body schema: application/json
required
object

SSM document for the workflow.

Name
required
string

A unique name for the workflow.

Array of objects (StepDocument)

List of step documents used in the SSM document.

Tags
Array of strings

List of tags for the workflow.

Responses

Request samples

Content type
application/json
{
  • "Content": {
    },
  • "Name": "string",
  • "StepDocuments": [
    ],
  • "Tags": [
    ]
}

Response samples

Content type
application/json
{
  • "Content": {
    },
  • "Name": "string",
  • "StepDocuments": [
    ],
  • "Tags": [
    ],
  • "DocumentFormat": "string",
  • "DocumentType": "string",
  • "DocumentVersion": "string",
  • "Status": "string"
}

Delete Workflow

Delete a selected version of the selected workflow. If no version is specified, delete all versions of the workflow.

Authorizations:
auth
path Parameters
workflow_name
required
string

Unique workflow name

query Parameters
version
string

Selected workflow version

workspace_id
string

Currently selected Workspace ID

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Update Workflow

Update a selected workflow by creating a new version. New workflow is created off of the latest version in SSM.

Authorizations:
auth
path Parameters
workflow_name
required
string

Unique workflow name

query Parameters
workspace_id
string

Currently selected Workspace ID

Request Body schema: application/json
required
object

SSM document for the workflow.

Tags
Array of strings

List of workflow tags.

Responses

Request samples

Content type
application/json
{
  • "Content": {
    },
  • "Tags": [
    ]
}

Response samples

Content type
application/json
{
  • "Description": "string",
  • "DocumentVersion": "string",
  • "Editor": "string",
  • "EditorId": "string",
  • "Name": "string",
  • "ReadOnly": true,
  • "Tags": [
    ],
  • "UpdatedDate": "string",
  • "WorkflowId": "string",
  • "WorkflowOwner": "string",
  • "WorkflowOwnerId": "string",
  • "WorkspaceId": "string",
  • "CreatedDate": "string",
  • "DefaultVersion": "string",
  • "DisplayName": "string",
  • "DocumentFormat": "string",
  • "DocumentType": "string",
  • "HashType": "string",
  • "IsDefault": true,
  • "LatestVersion": "string",
  • "Parameters": [
    ],
  • "PlatformTypes": "string",
  • "SSMDocument": "string",
  • "SchemaVersion": "string",
  • "SsmHash": "string",
  • "SsmName": "string",
  • "Status": "string",
  • "StepDocuments": [
    ],
  • "TenantId": "string",
  • "Versions": [
    ]
}

Get Workflow Name Availability

Check if workflow name is available for use.

Authorizations:
auth
path Parameters
workflow_name
required
string

Unique workflow name

Responses

Response samples

Content type
application/json
{
  • "available": true,
  • "message": "string",
  • "name": "string"
}

Get Workflow Content

Return the content of the default/selected version of the selected workflow.

Authorizations:
auth
path Parameters
workflow_name
required
string

Unique workflow name

query Parameters
version
string

Selected workflow version

workspace_id
string

Currently selected Workspace ID

Responses

Response samples

Content type
application/json
{
  • "Content": {
    },
  • "Description": "string",
  • "Name": "string",
  • "Parameters": [
    ],
  • "StepDocuments": [
    ],
  • "UpdatedDate": "string",
  • "WorkflowId": "string",
  • "showModal": true
}

Create Duplicate Workflow

Duplicate a specific version of the selected workflow.

Authorizations:
auth
path Parameters
workflow_name
required
string

Unique workflow name

query Parameters
name
string

Name of workflow to be duplicated

workspace_id
string

Currently selected Workspace ID

Request Body schema: application/json
NewName
required
string

Name of new workflow.

Version
string

Version of the workflow to be duplicated.

Responses

Request samples

Content type
application/json
{
  • "NewName": "string",
  • "Version": "string"
}

Response samples

Content type
application/json
{
  • "Description": "string",
  • "DocumentVersion": "string",
  • "Editor": "string",
  • "EditorId": "string",
  • "Name": "string",
  • "ReadOnly": true,
  • "Tags": [
    ],
  • "UpdatedDate": "string",
  • "WorkflowId": "string",
  • "WorkflowOwner": "string",
  • "WorkflowOwnerId": "string",
  • "WorkspaceId": "string",
  • "CreatedDate": "string",
  • "DefaultVersion": "string",
  • "DisplayName": "string",
  • "DocumentFormat": "string",
  • "DocumentType": "string",
  • "HashType": "string",
  • "IsDefault": true,
  • "LatestVersion": "string",
  • "Parameters": [
    ],
  • "PlatformTypes": "string",
  • "SSMDocument": "string",
  • "SchemaVersion": "string",
  • "SsmHash": "string",
  • "SsmName": "string",
  • "Status": "string",
  • "StepDocuments": [
    ],
  • "TenantId": "string",
  • "Versions": [
    ]
}

Get Workflow Information

Return the information for the default/selected version of the selected workflow, including workflow description and tags.

Authorizations:
auth
path Parameters
workflow_name
required
string

Unique workflow name

query Parameters
version
string

Selected workflow version

workspace_id
string

Currently selected Workspace ID

Responses

Response samples

Content type
application/json
{
  • "Description": "string",
  • "DocumentVersion": "string",
  • "Editor": "string",
  • "EditorId": "string",
  • "Name": "string",
  • "ReadOnly": true,
  • "Tags": [
    ],
  • "UpdatedDate": "string",
  • "WorkflowId": "string",
  • "WorkflowOwner": "string",
  • "WorkflowOwnerId": "string",
  • "WorkspaceId": "string",
  • "CreatedDate": "string",
  • "DefaultVersion": "string",
  • "DisplayName": "string",
  • "DocumentFormat": "string",
  • "DocumentType": "string",
  • "HashType": "string",
  • "IsDefault": true,
  • "LatestVersion": "string",
  • "Parameters": [
    ],
  • "PlatformTypes": "string",
  • "SSMDocument": "string",
  • "SchemaVersion": "string",
  • "SsmHash": "string",
  • "SsmName": "string",
  • "Status": "string",
  • "StepDocuments": [
    ],
  • "TenantId": "string",
  • "Versions": [
    ],
  • "Schedules": { }
}

Update Workflow Version

Update the default version of the workflow to a specific version.

Authorizations:
auth
path Parameters
workflow_name
required
string

Unique workflow name

query Parameters
version
string

Selected workflow version

workspace_id
string

Currently selected Workspace ID

Responses

Response samples

Content type
application/json
{
  • "Description": "string",
  • "DocumentVersion": "string",
  • "Editor": "string",
  • "EditorId": "string",
  • "Name": "string",
  • "ReadOnly": true,
  • "Tags": [
    ],
  • "UpdatedDate": "string",
  • "WorkflowId": "string",
  • "WorkflowOwner": "string",
  • "WorkflowOwnerId": "string",
  • "WorkspaceId": "string",
  • "CreatedDate": "string",
  • "DefaultVersion": "string",
  • "DisplayName": "string",
  • "DocumentFormat": "string",
  • "DocumentType": "string",
  • "HashType": "string",
  • "IsDefault": true,
  • "LatestVersion": "string",
  • "Parameters": [
    ],
  • "PlatformTypes": "string",
  • "SSMDocument": "string",
  • "SchemaVersion": "string",
  • "SsmHash": "string",
  • "SsmName": "string",
  • "Status": "string",
  • "StepDocuments": [
    ],
  • "TenantId": "string",
  • "Versions": [
    ],
  • "Schedules": { }
}

List Workflow Integrations

Return a list of integration instances for the default/selected version of a selected workflow.

Authorizations:
auth
path Parameters
workflow_name
required
string

Unique workflow name

query Parameters
movable_only
string

Only include integrations that can be moved to new workspace

version
string

Selected workflow version

workspace_id
string

Currently selected Workspace ID

Responses

Response samples

Content type
application/json
{
  • "integration_type": [
    ]
}

Connect Workspaces

List Workspaces

List all workspaces the user is authorized to view.

Authorizations:
auth
header Parameters
X-Fields
string <mask>

An optional fields mask

Responses

Response samples

Content type
application/json
{
  • "description": "string",
  • "name": "string",
  • "owner": "string",
  • "type": "string",
  • "workspace_id": "string",
  • "permissions": [
    ]
}

Create Workspace

Create a new workspace.

Authorizations:
auth
header Parameters
X-Fields
string <mask>

An optional fields mask

Request Body schema: application/json
description
string

Description of workspace

Array of objects (EntityBlock)

List of entities

name
string

Name of workspace

owner
string

Owner of workspace

type
string

Type of workspace

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "name": "string",
  • "owner": "string",
  • "type": "string",
  • "entities": [
    ]
}

Response samples

Content type
application/json
{
  • "description": "string",
  • "name": "string",
  • "owner": "string",
  • "type": "string",
  • "workspace_id": "string",
  • "permissions": [
    ]
}

Check Workspace Availability

Check if Workspace name is available for use.

Authorizations:
auth
header Parameters
X-Fields
string <mask>

An optional fields mask

Request Body schema: application/json
name
required
string

Workspace name to check

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "available": true,
  • "message": "string"
}

Get Workspace by Name

Get details of a specific workspace using workspace name.

Authorizations:
auth
path Parameters
workspace_name
required
string

Workspace name

header Parameters
X-Fields
string <mask>

An optional fields mask

Responses

Response samples

Content type
application/json
{
  • "description": "string",
  • "name": "string",
  • "owner": "string",
  • "type": "string",
  • "workspace_id": "string"
}

Delete Workspace

Delete a workspace specified by workspace_id

Authorizations:
auth
path Parameters
workspace_id
required
string

Unique workspace ID

Responses

Get Workspace by ID

Get details of a workspace specified by workspace_id.

Authorizations:
auth
path Parameters
workspace_id
required
string

Unique workspace ID

header Parameters
X-Fields
string <mask>

An optional fields mask

Responses

Response samples

Content type
application/json
{
  • "description": "string",
  • "name": "string",
  • "owner": "string",
  • "type": "string",
  • "workspace_id": "string",
  • "permissions": [
    ]
}

Update Workspace

Update a workspace specified by workspace_id.

Authorizations:
auth
path Parameters
workspace_id
required
string

Unique workspace ID

header Parameters
X-Fields
string <mask>

An optional fields mask

Request Body schema: application/json
description
string

Description of workspace

Array of objects (EntityBlock)

List of entities

name
string

Name of workspace

owner
string

Owner of workspace

type
string

Type of workspace

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "name": "string",
  • "owner": "string",
  • "type": "string",
  • "entities": [
    ]
}

Response samples

Content type
application/json
{
  • "description": "string",
  • "name": "string",
  • "owner": "string",
  • "type": "string",
  • "workspace_id": "string",
  • "permissions": [
    ]
}

Move Workflow and its Integrations to Another Workpace

It moves a workflow and all integrations it uses in new workspace. Following things are needed - Permissions the user needs in both workspaces: updateWorkflow updateIntegration updateSchedule updateExecution

Authorizations:
auth
path Parameters
workspace_id
required
string

Unique workspace ID

Request Body schema: application/json
move_all_integrations
boolean

If we need to move all integrations used in that workflow

workflow_name
string

Name of the workflow to move to the new workspace

workspace_id
string

Workspace ID to move the workflow into

Responses

Request samples

Content type
application/json
{
  • "move_all_integrations": true,
  • "workflow_name": "string",
  • "workspace_id": "string"
}

Compliance

Get Compliances

A cyber security compliance determines how compliant an asset is. It checks against specific security standards. This API returns list of all compliances supported in Spot. A compliance consists of one or more controls.

Authorizations:
auth
query Parameters
paginationKey
string (Paginationkey)

Token of the page to return.

paginationSize
integer (Paginationsize) [ 1 .. 100 ]
Default: 100

Number of items to return per page.

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "request": {
    },
  • "response": {
    },
  • "responseTime": 0
}

Get Compliance Count

Get the total number of compliances.

Authorizations:
auth

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "request": {
    },
  • "response": {
    },
  • "responseTime": 0
}

Get Compliance Controls

A control is countermeasures to avoid, detect, counteract, or minimize security risks of cloud assets. A control may be part of one or more compliances. A control is verified in one or more rules. This API returns the list of controls mapped to a specific compliance.

Authorizations:
auth
path Parameters
complianceName
required
string (Compliancename)
Example: SOC_2

The name of the cyber security compliance.

query Parameters
isAutomated
boolean (Isautomated)

If this is not a manual control, the value is True.

paginationKey
string (Paginationkey)

Token of the page to return.

paginationSize
integer (Paginationsize) [ 1 .. 100 ]
Default: 100

Number of items to return per page.

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "request": {
    },
  • "response": {
    },
  • "responseTime": 0
}

Get Compliance Controls Count

Get the total number of controls for the selected compliance.

Authorizations:
auth
path Parameters
complianceName
required
string (Compliancename)
Example: SOC_2

The name of the cyber security compliance.

query Parameters
isAutomated
boolean (Isautomated)

If this is not a manual control, the value is True.

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "request": {
    },
  • "response": {
    },
  • "responseTime": 0
}

Misconfiguration

Get Misconfigurations

This API returns the list of assets that have misconfigurations.

Authorizations:
auth
query Parameters
accountId
string (Accountid)

A comma-separated list of cloud account IDs. For AWS this is the account ID. For Azure, this is the subscription ID.

accountName
string (Accountname)

A comma-separated list of cloud account names.

assetId
string (Assetid)

The asset's ID (a cloud resource).

assetType
string (Assettype)

A comma-separated list of cloud resources for the service.

cloud
required
string (CloudProvider)
Enum: "aws" "azure"

Enumeration of supported cloud providers.

date
string <date> (Date)
Example: date=1997-11-11

The date the finding was most recently found (YYYY-MM-DD).

notAccountId
string (Notaccountid)

A comma-separated list of cloud account IDs to exclude. For AWS this is the account ID. For Azure, this is the subscription ID.

notAccountName
string (Notaccountname)

A comma-separated list of cloud account names to exclude

notAssetType
string (Notassettype)

A comma-separated list of cloud resources for the service to exclude.

notRegion
string (Notregion)
Example: notRegion=us-east-1

A comma-separated list of cloud regions to exclude.

notService
string (Notservice)

A comma-separated list of cloud services to exclude.

paginationKey
string (Paginationkey)

Token of the page to return.

paginationSize
integer (Paginationsize) [ 1 .. 100 ]
Default: 100

Number of items to return per page.

region
string (Region)
Example: region=us-east-1

A comma-separated list of cloud regions.

ruleName
string (Rulename)

The unique name of the rule.

service
string (Service)

A comma-separated list of cloud services.

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "request": {
    },
  • "response": {
    },
  • "responseTime": 0
}

Get Misconfigurations Count

This API returns a count of assets that have misconfigurations.

Authorizations:
auth
query Parameters
accountId
string (Accountid)

A comma-separated list of cloud account IDs. For AWS this is the account ID. For Azure, this is the subscription ID.

accountName
string (Accountname)

A comma-separated list of cloud account names.

assetId
string (Assetid)

The asset's ID (a cloud resource).

assetType
string (Assettype)

A comma-separated list of cloud resources for the service.

cloud
required
string (CloudProvider)
Enum: "aws" "azure"

Enumeration of supported cloud providers.

date
string <date> (Date)
Example: date=1997-11-11

The date the finding was most recently found (YYYY-MM-DD).

notAccountId
string (Notaccountid)

A comma-separated list of cloud account IDs to exclude. For AWS this is the account ID. For Azure, this is the subscription ID.

notAccountName
string (Notaccountname)

A comma-separated list of cloud account names to exclude

notAssetType
string (Notassettype)

A comma-separated list of cloud resources for the service to exclude.

notRegion
string (Notregion)
Example: notRegion=us-east-1

A comma-separated list of cloud regions to exclude.

notService
string (Notservice)

A comma-separated list of cloud services to exclude.

region
string (Region)
Example: region=us-east-1

A comma-separated list of cloud regions.

ruleName
string (Rulename)

The unique name of the rule.

service
string (Service)

A comma-separated list of cloud services.

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "request": {
    },
  • "response": {
    },
  • "responseTime": 0
}

Get Rules

Rules are configuration checks that detect misconfigurations in your cloud environment. Rules are cloud service provider specific. A rule is mapped to one or more controls. This API returns the list of rules that can determine the state of a specific control.

Authorizations:
auth
query Parameters
cloud
required
string (CloudProvider)
Enum: "aws" "azure"

Enumeration of supported cloud providers.

complianceName
string (Compliancename)
Example: complianceName=SOC_2

The name of the cyber security compliance.

controlId
string (Controlid)
Example: controlId=A1.2

The ID of the control defined in the compliance.

paginationKey
string (Paginationkey)

Token of the page to return.

paginationSize
integer (Paginationsize) [ 1 .. 100 ]
Default: 100

Number of items to return per page.

service
string (Service)

A comma-separated list of cloud services.

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "request": {
    },
  • "response": {
    },
  • "responseTime": 0
}

Get Rules Count

Rules are configuration checks that detect misconfigurations in your cloud environment. Rules are cloud service provider specific. A rule is mapped to one or more controls. This API returns the list of rules that can determine the state of a specific control.

Authorizations:
auth
query Parameters
cloud
required
string (CloudProvider)
Enum: "aws" "azure"

Enumeration of supported cloud providers.

complianceName
string (Compliancename)
Example: complianceName=SOC_2

The name of the cyber security compliance.

controlId
string (Controlid)
Example: controlId=A1.2

The ID of the control defined in the compliance.

service
string (Service)

A comma-separated list of cloud services.

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "request": {
    },
  • "response": {
    },
  • "responseTime": 0
}

Assets

Get Asset Sim Filter

Get a list of values in your organization for a specific filter type. For example, if you select accountId, you'll get a list of all the account IDs in your organization.

Authorizations:
auth
path Parameters
filterKey
required
string (Filterkey)
Enum: "accountId" "accountName" "region" "assetId" "assetName" "service" "assetType"

The name of the filter.

query Parameters
accountId
string (Accountid)

A comma-separated list of cloud account IDs. For AWS this is the account ID. For Azure, this is the subscription ID.

accountName
string (Accountname)

A comma-separated list of cloud account names.

affectedAssetsCount
string (Affectedassetscount)

The number of related assets affected by the finding.
Enter either a number or prefix it with one of these operators:

Operator Notation Example
Equals No prefix or ~eq~ 10 or ~eq~10
Not equals ~neq~ ~neq~10
Greater than ~gt~ ~gt~10
Greater than equals ~gte~ ~gte~10
Less than ~lt~ ~lt~10
Less than equals ~lte~ ~lte~10
Between two numbers ~bt~ ~bt~10,20

allAnomaliesCount
string (Allanomaliescount)

The total number of anomalies found for the asset identified that are still applicable today.
Enter either a number or prefix it with one of these operators:

Operator Notation Example
Equals No prefix or ~eq~ 10 or ~eq~10
Not equals ~neq~ ~neq~10
Greater than ~gt~ ~gt~10
Greater than equals ~gte~ ~gte~10
Less than ~lt~ ~lt~10
Less than equals ~lte~ ~lte~10
Between two numbers ~bt~ ~bt~10,20

allEventsCount
string (Alleventscount)

The total number of events found for the asset.
Enter either a number or prefix it with one of these operators:

Operator Notation Example
Equals No prefix or ~eq~ 10 or ~eq~10
Not equals ~neq~ ~neq~10
Greater than ~gt~ ~gt~10
Greater than equals ~gte~ ~gte~10
Less than ~lt~ ~lt~10
Less than equals ~lte~ ~lte~10
Between two numbers ~bt~ ~bt~10,20

allFindingsCount
string (Allfindingscount)

The sum of misconfigurations and vulnerabilities for today's date, and threats and anomalies identified that are still applicable today.
Enter either a number or prefix it with one of these operators:

Operator Notation Example
Equals No prefix or ~eq~ 10 or ~eq~10
Not equals ~neq~ ~neq~10
Greater than ~gt~ ~gt~10
Greater than equals ~gte~ ~gte~10
Less than ~lt~ ~lt~10
Less than equals ~lte~ ~lte~10
Between two numbers ~bt~ ~bt~10,20

allMisconfigCount
string (Allmisconfigcount)

The total number of misconfigurations found for the asset.
Enter either a number or prefix it with one of these operators:

Operator Notation Example
Equals No prefix or ~eq~ 10 or ~eq~10
Not equals ~neq~ ~neq~10
Greater than ~gt~ ~gt~10
Greater than equals ~gte~ ~gte~10
Less than ~lt~ ~lt~10
Less than equals ~lte~ ~lte~10
Between two numbers ~bt~ ~bt~10,20

allThreatsCount
string (Allthreatscount)

The total number of threats found for the asset identified that are still applicable today.
Enter either a number or prefix it with one of these operators:

Operator Notation Example
Equals No prefix or ~eq~ 10 or ~eq~10
Not equals ~neq~ ~neq~10
Greater than ~gt~ ~gt~10
Greater than equals ~gte~ ~gte~10
Less than ~lt~ ~lt~10
Less than equals ~lte~ ~lte~10
Between two numbers ~bt~ ~bt~10,20

allVulnCount
string (Allvulncount)

The total number of vulnerabilities found for the asset.
Enter either a number or prefix it with one of these operators:

Operator Notation Example
Equals No prefix or ~eq~ 10 or ~eq~10
Not equals ~neq~ ~neq~10
Greater than ~gt~ ~gt~10
Greater than equals ~gte~ ~gte~10
Less than ~lt~ ~lt~10
Less than equals ~lte~ ~lte~10
Between two numbers ~bt~ ~bt~10,20

assetId
string (Assetid)

The asset's ID (a cloud resource).

assetName
string (Assetname)

The name of the asset ID.

assetType
string (Assettype)

A comma-separated list of cloud resources for the service.

cloud
required
string (CloudProvider)
Enum: "aws" "azure"

Enumeration of supported cloud providers.

configEventsCount
string (Configeventscount)

The number of configuration events found for the asset.
Enter either a number or prefix it with one of these operators:

Operator Notation Example
Equals No prefix or ~eq~ 10 or ~eq~10
Not equals ~neq~ ~neq~10
Greater than ~gt~ ~gt~10
Greater than equals ~gte~ ~gte~10
Less than ~lt~ ~lt~10
Less than equals ~lte~ ~lte~10
Between two numbers ~bt~ ~bt~10,20

criticalEventsCount
string (Criticaleventscount)

The number of critical events found for the asset.
Enter either a number or prefix it with one of these operators:

Operator Notation Example
Equals No prefix or ~eq~ 10 or ~eq~10
Not equals ~neq~ ~neq~10
Greater than ~gt~ ~gt~10
Greater than equals ~gte~ ~gte~10
Less than ~lt~ ~lt~10
Less than equals ~lte~ ~lte~10
Between two numbers ~bt~ ~bt~10,20

criticalVulnCount
string (Criticalvulncount)

The number of critical vulnerabilities found for the asset.
Enter either a number or prefix it with one of these operators:

Operator Notation Example
Equals No prefix or ~eq~ 10 or ~eq~10
Not equals ~neq~ ~neq~10
Greater than ~gt~ ~gt~10
Greater than equals ~gte~ ~gte~10
Less than ~lt~ ~lt~10
Less than equals ~lte~ ~lte~10
Between two numbers ~bt~ ~bt~10,20

dataChangeEventsCount
string (Datachangeeventscount)

The number of data change events found for the asset.
Enter either a number or prefix it with one of these operators:

Operator Notation Example
Equals No prefix or ~eq~ 10 or ~eq~10
Not equals ~neq~ ~neq~10
Greater than ~gt~ ~gt~10
Greater than equals ~gte~ ~gte~10
Less than ~lt~ ~lt~10
Less than equals ~lte~ ~lte~10
Between two numbers ~bt~ ~bt~10,20

date
string <date> (Date)
Example: date=1997-11-11

The date the finding was most recently found (YYYY-MM-DD).

highMisconfigCount
string (Highmisconfigcount)

The number of high misconfigurations found for the asset.
Enter either a number or prefix it with one of these operators:

Operator Notation Example
Equals No prefix or ~eq~ 10 or ~eq~10
Not equals ~neq~ ~neq~10
Greater than ~gt~ ~gt~10
Greater than equals ~gte~ ~gte~10
Less than ~lt~ ~lt~10
Less than equals ~lte~ ~lte~10
Between two numbers ~bt~ ~bt~10,20

highVulnCount
string (Highvulncount)

The number of high vulnerabilities found for the asset.
Enter either a number or prefix it with one of these operators:

Operator Notation Example
Equals No prefix or ~eq~ 10 or ~eq~10
Not equals ~neq~ ~neq~10
Greater than ~gt~ ~gt~10
Greater than equals ~gte~ ~gte~10
Less than ~lt~ ~lt~10
Less than equals ~lte~ ~lte~10
Between two numbers ~bt~ ~bt~10,20

iamChangeEventsCount
string (Iamchangeeventscount)

The number of IAM change events found for the asset.
Enter either a number or prefix it with one of these operators:

Operator Notation Example
Equals No prefix or ~eq~ 10 or ~eq~10
Not equals ~neq~ ~neq~10
Greater than ~gt~ ~gt~10
Greater than equals ~gte~ ~gte~10
Less than ~lt~ ~lt~10
Less than equals ~lte~ ~lte~10
Between two numbers ~bt~ ~bt~10,20

infoVulnCount
string (Infovulncount)

The number of informational vulnerabilities found for the asset.
Enter either a number or prefix it with one of these operators:

Operator Notation Example
Equals No prefix or ~eq~ 10 or ~eq~10
Not equals ~neq~ ~neq~10
Greater than ~gt~ ~gt~10
Greater than equals ~gte~ ~gte~10
Less than ~lt~ ~lt~10
Less than equals ~lte~ ~lte~10
Between two numbers ~bt~ ~bt~10,20

isRisky
boolean (Isrisky)
Example: isRisky=true

If there are findings for the assets, the value is True.

lowMisconfigCount
string (Lowmisconfigcount)

The number of low misconfigurations found for the asset.
Enter either a number or prefix it with one of these operators:

Operator Notation Example
Equals No prefix or ~eq~ 10 or ~eq~10
Not equals ~neq~ ~neq~10
Greater than ~gt~ ~gt~10
Greater than equals ~gte~ ~gte~10
Less than ~lt~ ~lt~10
Less than equals ~lte~ ~lte~10
Between two numbers ~bt~ ~bt~10,20

lowVulnCount
string (Lowvulncount)

The number of low vulnerabilities found for the asset.
Enter either a number or prefix it with one of these operators:

Operator Notation Example
Equals No prefix or ~eq~ 10 or ~eq~10
Not equals ~neq~ ~neq~10
Greater than ~gt~ ~gt~10
Greater than equals ~gte~ ~gte~10
Less than ~lt~ ~lt~10
Less than equals ~lte~ ~lte~10
Between two numbers ~bt~ ~bt~10,20

mediumMisconfigCount
string (Mediummisconfigcount)

The number of medium misconfigurations found for the asset.
Enter either a number or prefix it with one of these operators:

Operator Notation Example
Equals No prefix or ~eq~ 10 or ~eq~10
Not equals ~neq~ ~neq~10
Greater than ~gt~ ~gt~10
Greater than equals ~gte~ ~gte~10
Less than ~lt~ ~lt~10
Less than equals ~lte~ ~lte~10
Between two numbers ~bt~ ~bt~10,20

mediumVulnCount
string (Mediumvulncount)

The number of medium vulnerabilities found for the asset.
Enter either a number or prefix it with one of these operators:

Operator Notation Example
Equals No prefix or ~eq~ 10 or ~eq~10
Not equals ~neq~ ~neq~10
Greater than ~gt~ ~gt~10
Greater than equals ~gte~ ~gte~10
Less than ~lt~ ~lt~10
Less than equals ~lte~ ~lte~10
Between two numbers ~bt~ ~bt~10,20

notAccountId
string (Notaccountid)

A comma-separated list of cloud account IDs to exclude. For AWS this is the account ID. For Azure, this is the subscription ID.

notAccountName
string (Notaccountname)

A comma-separated list of cloud account names to exclude

notAssetType
string (Notassettype)

A comma-separated list of cloud resources for the service to exclude.

notRegion
string (Notregion)
Example: notRegion=us-east-1

A comma-separated list of cloud regions to exclude.

notService
string (Notservice)

A comma-separated list of cloud services to exclude.

ordering
string (Ordering)
Default: "-allMisconfigCount"
Enum: "item" "-item" "accId" "-accId" "service" "-service" "assetType" "-assetType" "isRisky" "-isRisky" "colDate" "-colDate" "region" "-region" "allFindingsCount" "-allFindingsCount" "allVulnCount" "-allVulnCount" "criticalVulnCount" "-criticalVulnCount" "highVulnCount" "-highVulnCount" "mediumVulnCount" "-mediumVulnCount" "lowVulnCount" "-lowVulnCount" "infoVulnCount" "-infoVulnCount" "allMisconfigCount" "-allMisconfigCount" "highMisconfigCount" "-highMisconfigCount" "mediumMisconfigCount" "-mediumMisconfigCount" "lowMisconfigCount" "-lowMisconfigCount" "allEventsCount" "-allEventsCount" "configEventsCount" "-configEventsCount" "criticalEventsCount" "-criticalEventsCount" "dataChangeEventsCount" "-dataChangeEventsCount" "iamChangeEventsCount" "-iamChangeEventsCount" "affectedAssetsCount" "-affectedAssetsCount" "allAnomaliesCount" "-allAnomaliesCount" "allThreatsCount"

The field to sort the results by.

paginationKey
string (Paginationkey)

Token of the page to return.

paginationSize
integer (Paginationsize) [ 1 .. 100 ]
Default: 100

Number of items to return per page.

region
string (Region)
Example: region=us-east-1

A comma-separated list of cloud regions.

service
string (Service)

A comma-separated list of cloud services.

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "request": {
    },
  • "response": {
    },
  • "responseTime": 0
}