Skip to main content
API docs by Redocly

Crusoe Cloud API (v1alpha2)

Download OpenAPI specification:Download

Reference

Reference information for Crusoe Cloud's REST API.

Crusoe Cloud is currently in alpha. If you do not currently have access, please request access to continue.

Overview

Crusoe Cloud's REST API can be used to programmatically control resources such as creating Virtual Machines or fetching information about your organization.

Base URL and version

Crusoe Cloud's API is hosted at https://api.crusoecloud.com.

The current version while we are in private alpha is /v1alpha2.

Authentication

In order to authenticate to Crusoe Cloud's API, you must sign all requests using the following algorithm.

To begin creating a signed request, you need several pieces of information about the request being made:

  • The version of the signature being generated
  • The API access key ID and secret key
  • The signature payload
  • A timestamp for approximately when the request was created and sent, to prevent replay attacks

Once you have this information, you can send requests with the X-Crusoe-Timestamp and Authorization headers to authenticate to the API:

curl https://api.crusoecloud.com/v1alpha2/... \
 -H "X-Crusoe-Timestamp: <RFC3339 timestamp>" \
 -H "Authorization: Bearer <version:access_key_id:base64_encoded_signature>" \
 ...

Signature version

The current version of the signature is 1.0.

Getting an API access key and secret key

You can create an API access key and secret key by following the instructions in "Manage your API Keys".

Generating a signature

The signature payload consists of the following information, separated by newline ("\n") characters:

http_path
canonicalized_request_params
http_verb
timestamp_header_value

If there is no value (for example, no query params), then the line contains a single newline character.

The payload is used to generate a SHA256 HMAC signature, using a raw-urlsafe-base64 decoded version of the secret key as the HMAC secret key. The resulting HMAC signature is then base64 encoded and concatenated to the version and access_key_id using the : character.

Example

As an example, imagine we have:

  • An API access key ID (gYFONy-6QKS1acgUEQrR4Q) and secret key (uZFGf918DmiBUwBWv8lnEg)
  • A GET request being made to /v1alpha2/vms/types
  • At 2022-03-01T01:23:45+09:00

This would result in the following payload:

/v1alpha2/vms/types

GET
2022-03-01T01:23:45+09:00

The payload is then put through: raw_url_base64_encode(hmac_sha256("/v1alpha2/vms/types\n\nGET\n2022-03-01T01:23:45+09:00\n", raw_url_base64_decode("uZFGf918DmiBUwBWv8lnEg"))).

The output is then concatenated together with 1.0:6QKS1acgUEQrR4Q (the version and access key ID) and placed in the authorization header:

curl https://api.crusoecloud.com/v1alpha2/vms/types \
 -H "X-Crusoe-Timestamp: 2022-03-01T01:23:45+09:00" \
 -H "Authorization: Bearer 1.0:gYFONy-6QKS1acgUEQrR4Q:ZWFmMzVjMWMwODExNDc0OGY2ZTRmMzI0Y2UxOTI3YWQ2OTcwNmIzZTM4YWJmYjRkYWVjODBlYWE4MzY2ZGZkYw"

VMs

Retrieve details about all VMs that the logged in user owns or has access to.

Responses

Response samples

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

Create a new VM instance owned by the logged in user.

Request Body schema: application/json
commitment_period
integer <int64>
image_checksum
string
image_id
string
name
required
string
product_name
required
string
role_id
required
string
shutdown_script
string
ssh_public_key
required
string
startup_script
string

Responses

Request samples

Content type
application/json
{
  • "commitment_period": 6,
  • "image_checksum": "120EA8A25E5D487BF68B5F7096440019",
  • "image_id": "9f161e28-b629-442c-951c-77c68199f36e",
  • "name": "my-first-vm",
  • "product_name": "a100.2x",
  • "role_id": "09ae8411-0fbb-411c-898c-2b8f19622ae1",
  • "shutdown_script": "\"#!/bin/bash\\necho'goodbye'\"",
  • "ssh_public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCspdG97nTS/h4PEPq2QD2RYVK1jxFXLFZuSDMI8Rtxpucl6LDZLOghEYoj13lxKQnGtcsM3Iu68lh+4YgZe7CbI6cc/TxPbeAX2HJTqDh0J7+GAlLBHK9tsepC0QlhIDiazJptOPDZ3cesCBXdxSnzEbhDaqgYOfl393cp1fCeOKRIDWEP3H9CM25dCbWF66sTDziLsojJ9dMnxhgKm9/JkZc5gYncLT/2Ey+VWfV9Fs65mGUrBbQOn3c8S/nEk6WRcYn4PFOnIp0Mz+Chb50iCJrW677pllLnkTGSU+4c0H9J5z4HDG0I+91RoiQ0QsayFTYO1JtSn+THLuq98V+D",
  • "startup_script": "\"#!/bin/bash\\necho'hello'\""
}

Response samples

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

Get status of asynchronous operations

This resource retrieves information about the status of asynchronous operations initiated by the instances resource. All operations that are either in-flight or completed but not yet queried will be returned.

query Parameters
resource_id
string
Example: resource_id=452580d7-41d1-4b63-b4d7-4e4e21e95f96

Responses

Response samples

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

Get status of a single asynchronous operation

This resource retrieves information about the status of an asynchronous operation initiated by the instances resource. Only information about the operation specified in the path will be returned, or an HTTP 403 will be returned if the operation does not exist, was not initiated by the logged in user, or has expired.

path Parameters
operation_id
required
string

Responses

Response samples

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

Delete a VM that the logged in user owns.

path Parameters
vm_id
required
string

Responses

Response samples

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

Change the state of a VM the logged in user owns.

path Parameters
vm_id
required
string
Request Body schema: application/json
action
required
string
commitment_period
integer <int64>

Responses

Request samples

Content type
application/json
{
  • "action": "START",
  • "commitment_period": 6
}

Response samples

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

Retrieve information about the types of VMs that are available to purchase along with their prices.

Responses

Response samples

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

Roles

Retrieve details about roles that the logged in user belongs to or owns.

If querying for roles within an organization, the logged in user must be the owner of the organization.

query Parameters
org_id
string
Example: org_id=ee2a6bc3-aed5-4756-8995-9990a53d3a17

Responses

Response samples

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

Update details for a role that the logged in user owns.

Requests to this resource must contain the json-encoded representation of the changes they want to make to the role. Currently only the role's name can be changed.

query Parameters
role_id
required
string
Example: role_id=f058d0db-2fa4-4cf2-8cf1-dfbcfe05a814
Request Body schema: application/json
name
required
string

Responses

Request samples

Content type
application/json
{
  • "name": "Crusoe Energy"
}

Response samples

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

Create a new role that will be owned by the logged in user.

The logged in user must have the permission to create roles within the organization. A successful response from this resource contains details of the created role.

Request Body schema: application/json
name
required
string
organization_id
required
string

Responses

Request samples

Content type
application/json
{
  • "name": "Admin",
  • "organization_id": "ab4a6b00-aa5f-408e-a9fb-ac6de5eb45ab"
}

Response samples

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

Delete a role that the logged in user owns.

Delete operations cascade to VMs created under that role.

query Parameters
role_id
required
string
Example: role_id=f058d0db-2fa4-4cf2-8cf1-dfbcfe05a814

Responses

Response samples

Content type
application/json
{
  • "code": "401",
  • "message": "bad_credential"
}

Retrieve the list of users who are members of a role the logged in user owns.

query Parameters
role_id
required
string
Example: role_id=f058d0db-2fa4-4cf2-8cf1-dfbcfe05a814

Responses

Response samples

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

Update the membership for a role, and supports adding and removing users.

When removing a user, the association between the user and the role will be deleted.

query Parameters
role_id
required
string
Example: role_id=f058d0db-2fa4-4cf2-8cf1-dfbcfe05a814
Request Body schema: application/json
add
required
Array of strings
required
Array of objects (RelationUpdate contains information needed to grant a user permissions.)
remove
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "add": [
    ],
  • "grant": [
    ],
  • "remove": [
    ]
}

Response samples

Content type
application/json
{
  • "code": "401",
  • "message": "bad_credential"
}

Billing

Retrieve an intent to facilitate a Stripe action.

query Parameters
org_id
required
string
Example: org_id=ab4a6b00-aa5f-408e-a9fb-ac6de5eb45ab
intent_type
required
string
Example: intent_type=dashboard

Responses

Response samples

Content type
application/json
{}

Entities

Retrieve details about all active organizations the logged in user belongs to.

Responses

Response samples

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

Update details for an organization that the logged in user owns.

A successful response from this resource will contain the updated organization details.

query Parameters
org_id
required
string
Example: org_id=ab4a6b00-aa5f-408e-a9fb-ac6de5eb45ab
Request Body schema: application/json
organization_name
required
string

Responses

Request samples

Content type
application/json
{
  • "organization_name": "Crusoe Energy"
}

Response samples

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

Create a new organization owned by the logged in user.

A successful response from this resource will contain the json encoded organization details.

Request Body schema: application/json
organization_name
required
string

Responses

Request samples

Content type
application/json
{
  • "organization_name": "Crusoe Energy"
}

Response samples

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

Delete an organization owned by the logged in user.

Delete operations will cascade to roles and VMs, and all members will be removed from the organization.

query Parameters
org_id
required
string
Example: org_id=ab4a6b00-aa5f-408e-a9fb-ac6de5eb45ab

Responses

Response samples

Content type
application/json
{
  • "code": "401",
  • "message": "bad_credential"
}

Retrieve the list of users who are members of an organization (or have been invited) owned by the logged in user.

Responses

Response samples

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

Update the membership for an organization, as well as granting permissions to existing members.

For inviting and removing users from an organization, the logged in user must be the owner of the organization. For accepting an invite, the logged in user must have been invited to the organization.

Request Body schema: application/json
accept
boolean
required
Array of objects (RelationUpdate contains information needed to grant a user permissions.)
Array of objects (Invitee)
remove
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "accept": true,
  • "grant": [
    ],
  • "invite": [],
  • "remove": [
    ]
}

Response samples

Content type
application/json
{
  • "code": "401",
  • "message": "bad_credential"
}

Prospects

Create a new prospective customer in Crusoe Cloud.

Request Body schema: application/json
company
required
string
email
required
string
name
required
string
source
required
string
use_case
required
string

Responses

Request samples

Content type
application/json
{
  • "company": "crusoe",
  • "email": "[email protected]",
  • "name": "john",
  • "source": "portal",
  • "use_case": "training model to minimize energy usage"
}

Response samples

Content type
application/json
{
  • "success": true
}

Identities

Retrieve user details for the logged in user.

Responses

Response samples

Content type
application/json
{}

Update user details for the logged in user.

A successful response from this resource wil contain the updated user details.

Request Body schema: application/json
email
required
string
name
string

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Delete the account for the logged in user.

Delete operations will cascade to all entities the user owns (organizations, roles, vms).

Responses

Response samples

Content type
application/json
{
  • "code": "401",
  • "message": "bad_credential"
}

SSH-Keys

Retrieve the list of SSH public keys registered to the logged in user.

Responses

Response samples

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

Register a new SSH public key to the logged in user.

A successful response from this resource wil contain the created SSH key details.

Request Body schema: application/json
name
required
string
public_key
required
string

Responses

Request samples

Content type
application/json
{
  • "name": "John Doe",
  • "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAICpuH/fqCFLbAConChyVH6rZzSaxlnHSwQk6qvtPsf5E"
}

Response samples

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

Delete an SSH public key registered to the logged in user.

query Parameters
id
required
string
Example: id=6e28cad3-98e6-47a9-a9fc-1cd83a7f25c1

Responses

Response samples

Content type
application/json
{
  • "code": "401",
  • "message": "bad_credential"
}

Tokens

Retrieve all active/expired API tokens for the logged in user.

Responses

Response samples

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

Create a new token owned by the logged in user.

A successful response from this resource will contain json-encoded details of API token. This is the only time the customer will be able to view the secret key associated with the token.

Request Body schema: application/json
alias
required
string
expires_at
required
string

Responses

Request samples

Content type
application/json
{
  • "alias": "token1",
  • "expires_at": "2021-12-03T19:58:34Z"
}

Response samples

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

Delete an API token owned by the logged in user.

query Parameters
access_key
required
string
Example: access_key=WTUzcGibQ82y9_01h4MCdQ

Responses

Response samples

Content type
application/json
{
  • "code": "401",
  • "message": "bad_credential"
}