Skip to content
OpenRelay is in early access, and the /v1 API is stable. New capabilities ship in the changelog.
Skip to Content
API ReferenceComputeSandboxes

Create a sandbox template

Starts a build of a template from an image and its init steps. A sandbox can start from it once a build reaches the hosts.

Required permission

Requires the sandboxes.template_write permission. See Permissions for the roles and API key permissions that include it.

Command line

The orl CLI wraps this endpoint:

Guided workflow: orl sandbox template create

orl sandbox template create --image <image> --name <name>
POST
/v1/sandbox-templates

Authorization

apiKey
headerAuthorizationBearer <token>

OpenRelay API key. Send it as Authorization: Bearer or_… (legacy vl_… keys still work).

Header Parameters

Idempotency-Key?string

Makes a retried create safe. Choose one value per create you mean to make, 1 to 512 bytes (bytes, not characters), such as a UUID, and send it again on every retry of that create. The first request with a key runs, and a 2xx answer is kept for 24 hours: a repeat with the same key and the same body gets that answer back, with the same status and the header Idempotent-Replayed: true, and creates nothing. A batch create compares the body byte for byte; a VM or pod create compares the fields it decodes, so whitespace and key order do not count. A repeat while the first request is still running answers 409; repeat it a second later. The same key with a different body answers 422. An answer other than a 2xx is not kept, so a retry after a 4xx or a 5xx runs again. A 2xx too large to keep holds the key without it: every repeat answers 409 and creates nothing. Keys are scoped to the organization and the operation.

Length1 <= length

Request Body

application/json
  1. body
name*string
image*string

An image reference to build from.

init?array<string>

Commands run once while building.

cpu?integer
Range1 <= value
Default1
memoryMiB?integer
Default1024

Response Body

The template, building

application/json
  1. response
id*string
name*string
builtin?boolean
state*string
Value in"building""ready""failed"
createdAt?string
Formatdate-time
Example Request
curl -X POST 'https://api.openrelay.inc/v1/sandbox-templates' \  -H 'Content-Type: application/json' \  -d '{  "name": "string",  "image": "string"}'
Example Response
{  "id": "string",  "name": "string",  "builtin": true,  "state": "building",  "createdAt": "2019-08-24T14:15:22Z"}