Environments API

An environment is a saved size (CPU, memory, storage, GPU) with an optional container image of its own. Workspaces, jobs, apps and workflows run at an environment's size when you give its id (environmentId), instead of spelling out their resources. An environment with a base image or Dockerfile instructions is built into an image, versioned: each change builds a new version, and what tracks the environment moves to it once the build succeeds.

All endpoints require authentication via the X-API-Key header and the scope shown.

---

Environment Object

Field	Type	Description
_id	string	The environment's id: the environmentId workspaces, jobs, apps and workflows take
name	string	Unique within the organization
description	string	What it is for
vcpu	number	CPU cores
memoryGb	number	Memory in GB
storageGb	number	Ephemeral storage in GB
gpuCount	number	GPUs (0 for none)
gpuType	string | null	The GPU type when gpuCount is above 0
enabled	boolean	A disabled environment cannot be chosen
isPublic	boolean	Every user may use it
sharedWith	string[]	Users it is shared with, who may use and change it
usedBy	string[]	Users it is shared with to use only
ownerId, ownerName	string	Who created it (absent on the platform's own sizes)
organizationId	string | null	Its organization (null for the platform's own sizes)
baseImage	string	The image a build starts from
dockerfile	string	Instructions a build adds after the base image
buildStatus	string	The current version's build: pending, building, success or failed
buildError	string | null	Why the build failed
buildLogs	string[]	The build's log lines (on one environment, not in the list)
imageName	string	The built image of the current version
builtAt	string	When it was built
currentVersion	number	The version workloads that track the environment run
versions	object[]	Every version: version, baseImage, dockerfile, buildStatus, buildError, imageName, createdAt, builtAt
provides	object	What the image offers a workspace's IDEs (for example jupyter: installable), with probedAt
usageCount, inUse	number, boolean	How many apps, jobs, workspaces, workflows and models run on it (on one environment, and in the list with includeUsage); an environment in use keeps its size
createdAt, updatedAt	string	ISO 8601

---

GET /api/v1/environments

The environments you may use: the platform's sizes, your organization's and those shared with you.

Scope: workspaces:read

Query Parameters

Parameter	Type	Required	Description
enabledOnly	boolean	No	Only enabled environments
includeUsage	boolean	No	Add how many resources run on each (usageCount, inUse)
limit	integer	No	Results per page
cursor	string	No	meta.nextCursor of the previous page

Response 200 OK: a page of the environments you may use, meta.nextCursor set while more remain.

---

POST /api/v1/environments

Create an environment. With a baseImage or dockerfile, its image builds as version 1: poll the environment until buildStatus is success. An environment for a workflow builds FROM the platform's workflow-worker image.

Scope: workspaces:write

Request Body

Field	Type	Required	Description
name	string	Yes	Unique within your organization
description	string	No	What it is for
cpu	number	No	CPU cores (default 1)
memoryGb	number	No	Memory in GB (default 4)
storageGb	number	No	Ephemeral storage in GB (default 20)
gpuCount	number	No	GPUs (default 0)
gpuType	string	No	GPU type, with gpuCount above 0 (for example nvidia-t4)
isPublic	boolean	No	Every user may use it
baseImage	string	No	The image to build from
dockerfile	string	No	Instructions to add after the base image (no FROM when baseImage is set)

Response 201 Created: the new environment.

---

GET /api/v1/environments/:id

An environment, with its build state and versions.

Scope: workspaces:read

Parameter	Type	Required	Description
id	string	Yes	Environment id

Response 200 OK: the environment.

---

PATCH /api/v1/environments/:id

Change an environment. A new baseImage or dockerfile builds a new version. Its size cannot change while something uses it.

Scope: workspaces:write

Parameter	Type	Required	Description
id	string	Yes	Environment id

Request Body (every field optional)

Field	Type	Description
name, description	string	Its name and description
cpu, memoryGb, storageGb, gpuCount	number	Its size
gpuType	string	GPU type
enabled	boolean	Enable or disable it
isPublic	boolean	Every user may use it (administrators only)
baseImage, dockerfile	string	A new image recipe (builds a new version)

Response 200 OK: the updated environment.

---

DELETE /api/v1/environments/:id

Delete an environment and its images. An environment that an app, job, workspace, workflow or model still uses is refused (422 resource-in-use, naming what uses it).

Scope: workspaces:write

Parameter	Type	Required	Description
id	string	Yes	Environment id

Response 204 No Content

---

GET /api/v1/environments/base-image-status

Whether each environment's image is built from what its base image tag points to now.

Scope: workspaces:read

Response 200 OK: statuses, by environment id, each with its baseImage and a status: current (built from the tag's present digest), outdated (the tag has moved since; rebuild to take the new base) or unknown (the base is not in this deployment's registry, with the reason).

---

POST /api/v1/environments/:id/rebuild

Build an environment again, as a new version, from its base image tag's present digest. The versions in use keep running until the build succeeds; then what tracks the environment moves to the new version.

Scope: workspaces:write

Parameter	Type	Required	Description
id	string	Yes	Environment id

Response 200 OK: { "status": "rebuilding", "fromVersion", "toVersion" }, or { "status": "current" } when the image is already built from the present digest.