Documentation

REST API v1 (deprecated)

The API can be accessed at https://cloud.gurobi.com/api. There are 4 API endpoints:

Endpoint	Type
licenses	GET
machines	GET
launch	POST
kill	POST

API Access Id and Secret Key

Each account on cloud.gurobi.com contains an API access ID and secret key. The access ID is a string like CoBj64kvnTg5z3ehH and is used to identify API requests. The secret key is a string like TJJfLtS_LIRAwpqXh3srS64Ur1PdCHI3DmkNXhemzZm. It should be kept secret and is used to sign requests to verify they are from you. You can obtain your access ID and secret key by clicking the API access button in the Account Info panel on the Launcher page.

API signatures

Each API request must include the user's access ID, the current data in ISO8601 format, and be signed with the user's secret key. This authentication system is similar to the one from Amazon Web Services

Signature = Base64 (HMAC-SHA1( StringToSign, SecretAccessKey) )

Date: ISO8601 date string

HTTP-VERB: GET | POST

StringToSign = HTTP-VERB + '&' + param_0 + '=' val_0 + '&' ... '&' param_n + '=' val_n '&' Date

The signature should be included in the x-gurobi-signature header of the request. The date should be included in the x-gurobi-date header of the request.

It can be a little tricky to correctly compute the BASE64 encoding of the HMAC-SHA1. To help with this we provide a sample encoding that you can use to verify your code.

HMAC-SHA1("The quick brown fox jumps over the lazy dog", "key") = de:7c:9b:85:b8:b7:8a:a6:bc:8a:7a:36:f7:0a:90:70:1c:9d:b4:d9
Base64(HMAC-SHA1("The quick brown fox jumps over the lazy dog", "key") = 3nybhbi3iqa8ino29wqQcBydtNk=

Note that the Base64 encoding should be trimmed of all line breaks.

The order of parameters and values in the StringToSign should match that of your HTTP request's query string.

API Endpoints

/api/licenses

Making a GET request to /api/licenses returns a JSON response containing an array of licenses associated with a user's id. The following fields are contained in each license object:

• licenseId: The numeric id of the license
• credit: The remaining credit on the license
• expiration: The expiration date of the license
• ratePlan: The type of license, one of the following:
  • nocharge - A free trial license
  • standard - A standard paid license

/api/machines

Making a GET request to /api/machines returns a JSON response containing an array of machines associated with a user's id. The following fields are contained in each machine object:

• _id: The id of the machine. This id is used to kill machine.
• state: The state of the machine, one of the following:
  • launching - The user has requested the machine be launched
  • pending - The machine has been launched but has not yet booted
  • obtaining license - The machine is booted, but has not received a Gurobi license
  • idle - The machine can receive jobs and is not currently running a job
  • running - The machine can receive jobs and is currently running a job
  • killing - The user has requested the machine be killed
  • shutting down - The machine is in the process of shutting down
  • launch error - The machine could not be launched
• DNSName: The DNS name of the machine. This will be - when the machine is in the launching or pending state. The name of the machine is populated once the machine's state changes to obtaining license.
• machineType: The type of the machine, one of the following:
  • c4.large
  • c4.2xlarge
  • c4.4xlarge
  • c4.8xlarge
  • r3.8xlarge
• createTime: The time the machine was created/launched.
• region: The region where the machine was launched, one of the following:
  • us-east-1
  • us-west-1
  • us-west-2
  • eu-central-1
  • eu-west-1
  • ap-northeast-1
  • ap-southeast-1
  • ap-southeast-2
• licenseType: The type of license installed on the machine, one of the following:
  • light compute server
  • full compute server
  • distributed worker
• idleShutdown: The time (in minutes) after which the machine should shutdown if idle.
• licenseId: The license Id associated with this machine
• userPassword: The password used to access this machine

/api/launch

Making a POST request to /api/launch will launch machines and return an array of machine objects, as described in /api/machines of the launched machines.

The following parameters can be included in the POST request:

• numMachines: The number of machines to launch. If more than 1 machine is requested, the remaining machines will be distributed workers. This argument is required.

• licenseType: The type of license installed on the machine, one of the following:

  • light compute server
  • full compute server

  If not present, this defaults to light compute server.

• licenseId: The license id that the machines should be launched under. If not present, the machines are launched under the license with the smallest license id.

• userPassword: The password to set on these machines. If not present, a password is autogenerated for you. Query /api/machines to retrieve the autogenerated password.

• region: The region where the machine should be launched, one of the following:

  • us-east-1
  • us-west-1
  • us-west-2
  • eu-central-1
  • eu-west-1
  • ap-northeast-1
  • ap-southeast-1
  • ap-southeast-2

  If not present, this defaults to us-east-1.

• idleShutdown: The time (in minutes) after which the machine should shutdown if idle. If not present, this defaults to 60 minutes.

• machineType: The type of machine to launch, one of the following:

  • c4.large
  • c4.2xlarge
  • c4.4xlarge
  • c4.8xlarge
  • r3.8xlarge

  If not present, this defaults to c4.2xlarge.

• GRBVersion: The version of Gurobi to run on the machine, one of the following:

  • 7.0
  • 7.5
  • 8.0

/api/kill

Making a POST request to /api/kill will kill a set of machines. The following parameter must be included in the POST request:

• machineIds: A JSON array of machine ids to kill.

A JSON array of machine objects, as described in /api/machines, corresponding to the machines that were killed is returned.

API Errors

If you send a bad request to any of the API endpoints, cloud.gurobi.com will respond with an HTTP status code of 400. In addition the server will include an error message in it's response.

Below are a list of common error messages:

• Endpoint requires a GET: This error is issued by the license and machines endpoints when the method is not a GET.

• Endpoint requires a POST: This error is issued by the launch and kill endpoints when the method is not a POST.

• Missing X-Gurobi-Signature Header: This error is issued when your request does not contain the x-gurobi-signature header.

• Missing X-Gurobi-Date Header: This error is issued when your request does not contain the x-gurobi-date header.

• Too large of time skew: This error is issued when the time included in the x-gurobi-date is too far away from time on the cloud.gurobi.com.

• Invalid User Id: This error is issued when the user access ID is not found in cloud.gurobi.com's database.

• Invalid Signature: This error is issued when the signature generated by cloud.gurobi.com does not match your signature in the x-gurobi-signature header. To help debug invalid signatures cloud.gurobi.com includes in this error message the StringToSign it generated from your request. You should verify that the StringToSign generated by cloud.gurobi.com matches yours, and that you are using the correct API secret key, and properly executing the HMAC-SHA1 and BASE64 encoding to generate the signature.

• Invalid License Type: This error is issued by the launch endpoint when the licenseType parameter included in your request is not one of the following: light compute server, full compute server.

• Invalid Region: This error is issued by the launch endpoint when the region parameter included in your request is not one of the following: us-east-1, us-west-1, us-west-2, eu-central-1, eu-west-1, ap-northeast-1, ap-southeast-1, ap-southeast-2.

• Invalid Machine Type: This error is issued by the launch endpoint when the machineType parameter included in your request is not one of the following: c4.large, c4.2xlarge, c4.4xlarge, c4.8xlarge, r3.8xlarge.

• Invalid License Id: This error is issued by the launch endpoint when the licenseId parameter included in your request can not be found in your account.

• Invalid Number of Machines: This error is issued by the launch endpoint when the numMachines parameter is missing or not a valid number.

• Invalid Machine Ids: This error is issued by the kill endpoint when the machineIds parameter is missing or not a valid JSON array of machine ids to kill.