Welcome to Spotinst API Documentation!

 Welcome to the heart and soul of Spotinst: our API, which allows you to manage and operate your Spotinst account using conventional RESTful APIs. Whatever you can do via our portal, you can also do via our API.


Except for content explicitly made available to the general public, access and use of this site and all content herein is restricted to users authorized by Spotinst and may be subject to confidentiality restrictions. Please also note that the information contained herein is for informational purposes only and to the extent, it conflicts with the terms of your contractual agreements with Spotinst, the terms of those contracts will govern.


This page explains the semantics of our REST API. It includes information on:

  • How to ask a service about itself: what fields it supports, which fields are filterable
  • How to get only the information you want by filtering and sorting
  • The structure of our JSON responses in different scenarios

HTTP Protocol

The Spotinst API supports HTTP Protocol version 1.1 or later. While some calls may work with the deprecated 1.0 version, this is not guaranteed. Please ensure that your client communicates using at least version 1.1.

API Endpoint

Spotinst API URL: https://api.spotinst.io

Please note – We enforce using the secure endpoint (https) for our production API to ensure the privacy of your data.

REST Semantic

Our API services are RESTful. REST (Representational State Transfer) is a type of software architecture in which requests model the communication from a web browser to a web server. Below are the central REST methods used in our API services, and their uses:

REST Method Use
POST Create
GET Read
PUT Update


In our documentation, we use curl to make HTTP requests. cURL is a command-line tool for transferring files with URL syntax, supporting FTP, FTPS, HTTP, HTTPS, SCP, SFTP, TFTP, TELNET, DICT, LDAP, LDAPS, and more. Example scripts have been provided on each API wiki page to illustrate the structure of the curl commands you will need to run Spotinst API services. In addition, an example of how to a make a generic POST request is shown below.

$ curl -X POST
-H "Content-Type: application/json"
-H "Authorization: Bearer <TOKEN>"
-d @some.jsonfile 'http://api.spotinst.io/aws/ec2/group'
Request Parameter Description
-H "Content-Type: " Indicates which type of data you pass, could be “application/json” or “application/x-www-form-urlencoded
-H "Authorization: Bearer <TOKEN>" Retrieves your authentication token
-X The type of the request. in this case “POST
-d Indicates that you are going to upload a file or an encoded payload
https://api.spotinst.io/aws/ec2/group Endpoint URL and path for your request
 Use Single Quotes Around Your Request URL Some requests require single quotes around your request URL, as in the above curl request. If you get an error message from your UNIX shell, make sure your request URL has single quotes before troubleshooting further. For more information on how UNIX shell quotes and escaping work, see this documentation on quotes and escaping in shells.

JSON Fields Types

POST and PUT requests require JSON data. For PUT requests, only the JSON fields included in a request will be updated. All other fields will be unchanged. Different fields require different types of values. The table of types below extends those defined in the JSON standard.

Type Description Example
Boolean True or false true
String(100) A string of 100 characters or less “Spotinst Cloud”
Int An integer 87
Decimal A generic decimal number 3.0
Float A floating-point number with 23-bit precision 3.14…
Double A floating-point number with 64-bit precision 3.14…
Enum One of a number of predetermined values “male” or “female”
Money A floating-point numeric value used to represent money 19.23
Timestamp A date and time string in the form YYY-MM-DD HH:MM:SS “2009-01-14 05:41:04”
Date A date and time string in the form YYY-MM-DD HH:MM:SS “2009-01-14 05:41:04”
Multi-Object A wrapper for any sub-fields under the current field “countries_and_brands”: [ { “country”: “FR”, “brand”: { “id”: 466, “name”: “PKR” } } ]
Array A list containing one or more values [87, 45, 99.12, 101.71]

JSON fields and values use underscores, e.g., audit_type_direct.

Organization and Accounts

Each Spotinst account is assigned to an Organization and a set of environment Accounts. Each account should be linked to either a Cloud provider account or a Multai Load Balancer Account.

Each Account will have an Account ID that needs to be used while performing an API call to resources in the account.

To locate the Account Id, please navigate to the account settings and locate the Account ID value.


Organizations with a single Account

Each API call you make can be used with or without the account ID.

Organizations with multiple Accounts

Each API call you make should be appended to the account ID. For example:

GET https://api.spotinst.io/aws/ec2/group?accountId=act-123de678

This call will return the list of Elastigroups for the specific Account used.

 Please note – If no accountId is provided, the default account for the Organization will be used