Scripting with the API

The management API behind the console also answers a bearer token. Set ORC_API_TOKEN (at least 24 characters) and send it on every request:

export ORC_API_TOKEN='a-long-random-token-of-24-chars-or-more'
curl -H "Authorization: Bearer $ORC_API_TOKEN" https://example.com/api/admin/instances

The token grants the same access as the global administrator. It is compared in constant time and is never shown on the Settings page. Keep it secret.

The full list of endpoints is in the management API reference.

Create a workspace

POST /api/admin/instances takes the same fields as the form. Names and addresses must be unique, and the address must be valid.

curl -X POST -H "Authorization: Bearer $ORC_API_TOKEN" -H 'Content-Type: application/json' \
  -d '{
        "Name": "Acme Research",
        "Slug": "acme",
        "Description": "Research workspace",
        "ShowOnLanding": true,
        "StartNow": true,
        "Environment": { "MSK_LOW_MEMORY": "true" }
      }' \
  https://example.com/api/admin/instances

The answer holds the workspace and an operation. Creating can take minutes, because the first one pulls the image. Follow the operation:

curl -H "Authorization: Bearer $ORC_API_TOKEN" https://example.com/api/admin/operations/<operation id>

Suggest a valid address

curl -H "Authorization: Bearer $ORC_API_TOKEN" "https://example.com/api/admin/slug?name=Acme%20Research"

The answer has Slug, IsValid and, when it is not valid, a Reason.

Start, stop and keep warm

curl -X POST -H "Authorization: Bearer $ORC_API_TOKEN" https://example.com/api/admin/instances/acme/start
curl -X POST -H "Authorization: Bearer $ORC_API_TOKEN" https://example.com/api/admin/instances/acme/stop
curl -X POST -H "Authorization: Bearer $ORC_API_TOKEN" -H 'Content-Type: application/json' \
     -d '{"Hours": 24}' https://example.com/api/admin/instances/acme/keep-warm

start returns at once with the workspace's start status. Poll GET /api/public/instances/acme/status until it is ready. GET /api/graph/ready on the workspace itself answers true when Studio is ready.

Back up all workspaces

for slug in $(curl -s -H "Authorization: Bearer $ORC_API_TOKEN" https://example.com/api/admin/instances | jq -r '.[].Slug'); do
  curl -s -X POST -H "Authorization: Bearer $ORC_API_TOKEN" "https://example.com/api/admin/instances/$slug/stop"
  curl -s -H "Authorization: Bearer $ORC_API_TOKEN" -o "$slug.tar.gz" "https://example.com/api/admin/instances/$slug/backup"
done

Stopping clears keep warm, so set it again afterwards for workspaces that need it. See Backups.

Accounts and variables

PUT /api/admin/accounts and PUT /api/admin/environment replace the global lists. They are the global administrator's, and on a managed node they are refused.

curl -X PUT -H "Authorization: Bearer $ORC_API_TOKEN" -H 'Content-Type: application/json' \
  -d '[{"UserName":"jane","FirstName":"Jane","LastName":"Doe","Email":"jane@example.com","Password":"a-strong-password-1","IsAdmin":false}]' \
  https://example.com/api/admin/accounts

Property names

Property names are PascalCase, and times are unix milliseconds.