Skip to main content

HTTP API

The current version is 1, so calls to api.rerobots.net that lack a version route default to v1. To request this or any particular version, in requests include an Accept header, e.g.,

application/vnd.rerobots.v1+json

Response includes headers concerning rate limiting:

X-RateLimit-Limit: N
X-RateLimit-Remaining: M
X-RateLimit-Reset: T

where T is seconds since The Epoch, and it is invariant that M < N. (It cannot be that M = N because the response header is sent if and only if a request was made.) In the future we may modify this to not count some requests against the limit, e.g., if a redirect is required. Each subsequent request will cause X-RateLimit-Remaining to be decremented until it reaches 0, after which no more requests will be accepted until the current time passes T.

authentication

Not all commands require authentication. In the text below, commands for which authentication is provided are with respect to the username in the given token. In the API description, this user is called "the user".

Get API tokens through the Web UI. (Read instructions about how to do so.)

commands

GET /

list summary of commands available in this version of the HTTP API

GET /workspaces

list known workspace types. Note that this list is independent of which deployments currently exist or are available to use.

POST /revoke/:SHA256-of-token

Revoke API token that belongs to user and has SHA256 hash equal to second part of the route.

A valid API token can be used to revoke itself.

POST /purge

Delete all authetication (API) tokens associated with the user. To do this, the user and password pair or an existing token of sufficient capabilities must be provided. If both are provided, then only the user and password pair is checked.

GET /deployments{/workspace_type}

Get list of all deployments or deployments of a specific workspace type. Note that currently available workspace types can be obtained using GET /workspaces. This supports pagination that is entirely similar to that of GET /instances.

Optional query parameters are the following:

GET /deployment/:deploymentID

Get information about workspace deployment. Response is a JSON object with some or all of the following:

GET /queuelen/:deploymentID

Get length of the use-queue for a workspace deployment. The length is defined as 0 if the deployment is not currently being used and if there is no reservation that applies to it. Otherwise, 1+N, where N is the number of reservations that apply to it. Because a reservation can apply to (and thus, be satisfied by) more than one workspace deployment, N is an upper bound.

If the deployment ID is not recognized, then 404 (Not Found) status code is returned.

Note that a subsequent request for an instance of this workspace deployment may not succeed, despite receiving 0 length in the previous response. This is simply a matter of race conditions with other potential users.

GET /firewall/:instanceID

Get ordered list of firewall rules for workspace instance. Following the convention of Linux iptables, the first rule that an incoming packet matches decides outcome.

Response is in JSON. The main field is rules; it is a list of (source, action) pairs, or if the corresponding chain is not created yet, none.

DELETE /firewall/:instanceID

Clear all firewall rules for workspace instance. The default behavior is to drop all incoming messages, which is thus the consequence of this command. Use POST /firewall/:instanceID with an empty body (i.e., no JSON payload) to allow incoming packets from the issuer of the POST request.

POST /firewall/:instanceID

Append firewall rules to existing chain for workspace instance. The payload is a JSON object with one or more of the following:

POST /new/{:workspace_type,:deploymentID}

Request new instance. Options are described below. Currently the only levels of specificity are workspace type or deployment ID. If a workspace type is given, then an appropriate deployment is selected depending on availability: if one is immediately available, then it is used; otherwise one with minimal queue length is selected. If a deployment ID is given, then that deployment is used.

Optional payload is JSON object with some or all of the following:

Response is a JSON object with some or all of the following:

Note that success: true in the response does not imply that the instance has finished initialization. For example, creating a new VPN can require 30 or more seconds, so new client credentials requests (POST /vpn/:instanceID) will not yet succeed.

To get the current status of the instance, including whether it is ready to use, check GET /instance/:instanceID.

POST /terminate/:instanceID

Terminate (end) the running of an instance. The instance cannot be used again if this command succeeds.

GET /instances

Get list of all active instances that were created by the user. This command requires authentication, and the user key of the JWT determines which instances are shown.

Optional query keys are the following:

Response contains:

GET /instance/:instanceID

Get information about workspace instance to which the user has read-access. Response is a JSON object with some or all of the following:

GET /vpn/:instanceID

Get details about the VPN associated with this instance, if there is one. Response is a JSON object with some or all of the following:

If there is no VPN for this instance (but the instance otherwise exists), then the response is

{"status": "nil"}

POST /vpn/:instanceID

Get credentials for a new client to join the VPN associated with this instance. The response has two parts:

GET /reservations

Get list of active reservations associated with the user's account.

Response is a JSON object with:

Each item in the list reservations is a JSON object with:

DELETE /reservation/:reservationID

Delete a reservation. This process cannot be undone. In particular, any progress toward using one of the matching workspace deployments will be lost.

POST /ci/new

Start new CI build. Body data in the request should be JSON containing: