Workspaces

Create a workspace

Changed on
post/api/v1/workspaces

Request

  • Base URL: / (relative, and the document was published on a file host, not at the API’s origin)
  • URL: /api/v1/workspaces
  • Auth: none declared

Headers

X-Axisml-Tenantstring

Active tenant for the request (fallback for the axisml.tenant cookie).

Request body

argsstring[]

Container args override.

commandstring[]

Container entrypoint override.

containerPortinteger

Port the dev server listens on; defaults from the image when omitted.

descriptionstring

Free-text workspace description.

displayNamestring

Human-readable workspace label.

imagestring required

Container image for the dev environment.

namestring required

Workspace name (unique within the tenant).

poolNamestring required

Resource pool to schedule the workspace onto.

unitNamestring required

Resource unit (shape) within the pool.

Example request

{
  "containerPort": 8888,
  "description": "JupyterLab interactive development environment.",
  "displayName": "Vision team dev environment",
  "image": "registry.axisml.io/dev/jupyter:3.0.0",
  "lifecycle": {
    "idleTimeoutSeconds": 3600
  },
  "name": "notebook-dev",
  "poolName": "gpu-a100",
  "unitName": "a100-1x",
  "volumes": [
    {
      "mountPath": "/home/jovyan/work",
      "name": "notebook-data"
    }
  ]
}

Response

Workspace created.

admissionMessagestring

Human-readable detail for the current admission wait.

admissionReasonstring

Stable reason why the workspace is still waiting for admission.

admittedReplicasinteger

Pods holding durable capacity and tenant-quota admission.

argsstring[]

Container args override.

commandstring[]

Container entrypoint override.

computeNamespacestring

Underlying compute (Kubernetes) namespace hosting the workspace.

containerPortinteger required

Port the dev server listens on inside the container.

createdAtstring date-time required

Time the workspace was created.

descriptionstring

Free-text workspace description.

desiredState'Running' | 'Stopped'
displayNamestring

Human-readable workspace label.

idstring uuid required

Stable workspace identifier.

imagestring required

Container image for the dev environment (e.g. jupyter, code-server).

lastStartedAtstring date-time nullable

Time the workspace was last started.

lastStoppedAtstring date-time nullable

Time the workspace was last stopped.

messagestring

Human-readable status detail for the current phase.

namestring required

Workspace name (unique within the tenant).

namespacestring required

Platform tenant namespace the workspace belongs to.

ownerstring required

Username of the workspace owner.

ownerIdstring uuid

User ID of the workspace owner.

phase'Queued' | 'Creating' | 'Starting' | 'Running' | 'Degraded' | 'Failed' | 'Stopped' | 'Deleting' | 'Deleted' | 'Pending'

Derived from compute service phase + replicas. Hoisted to the top of Workspace for B-tree filtering.

poolNamestring

Resource pool the workspace is scheduled onto.

readyReplicasinteger

Pods that have passed readiness.

replicasinteger

Desired pod count (0 when stopped).

resourcesResourceMap

Kubernetes-style resource quantity map (e.g., {"cpu": "100", "memory": "1Ti", "nvidia.com/gpu": "8"}).

tenantDisplayNamestring

Human-readable tenant name.

tenantNamestring required

Tenant identifier owning the workspace.

unitNamestring

Resource unit (shape) within the pool.

updatedAtstring date-time required

Time the workspace was last updated.

Example response

{
  "args": [
    "--NotebookApp.token="
  ],
  "command": [
    "start-notebook.sh"
  ],
  "computeNamespace": "axisml-team-vision",
  "containerPort": 8888,
  "createdAt": "2026-06-20T08:00:00Z",
  "description": "JupyterLab interactive development environment.",
  "desiredState": "Running",
  "displayName": "Vision team dev environment",
  "endpoint": {
    "accessUrl": "https://axisml.example.com/ws/team-vision/notebook-dev/",
    "internalDns": "notebook-dev.axisml-team-vision.svc.cluster.local",
    "tools": [
      {
        "label": "JupyterLab",
        "name": "jupyter",
        "url": "https://axisml.example.com/ws/team-vision/notebook-dev/lab"
      },
      {
        "label": "VS Code",
        "name": "vscode",
        "url": "https://axisml.example.com/ws/team-vision/notebook-dev/vscode/"
      },
      {
        "label": "Terminal",
        "name": "terminal",
        "url": "https://axisml.example.com/ws/team-vision/notebook-dev/terminals/1"
      }
    ]
  },
  "env": [
    {
      "name": "JUPYTER_ENABLE_LAB",
      "value": "yes"
    }
  ],
  "id": "f1e2d3c4-5b6a-4798-8c0d-1e2f3a4b5c6d",
  "image": "registry.axisml.io/dev/jupyter:3.0.0",
  "lastStartedAt": "2026-06-28T09:00:00Z",
  "lifecycle": {
    "idleTimeoutSeconds": 3600
  },
  "message": "Workspace is ready.",
  "name": "notebook-dev",
  "namespace": "team-vision",
  "owner": "li.wei",
  "ownerId": "3a2b1c0d-4e5f-6789-abcd-ef0123456789",
  "phase": "Running",
  "poolName": "gpu-a100",
  "readyReplicas": 1,
  "replicas": 1,
  "resources": {
    "cpu": "4",
    "memory": "32Gi",
    "nvidia.com/gpu": "1"
  },
  "tenantDisplayName": "Vision Team",
  "tenantName": "team-vision",
  "unitName": "a100-1x",
  "updatedAt": "2026-06-28T09:30:00Z",
  "volumes": [
    {
      "mountPath": "/home/jovyan/work",
      "name": "notebook-data",
      "used": "12Gi"
    }
  ]
}

Changes

  • c37335303c98Revision changes
    • warning

      added the new Queued enum value to the //// response property for the response status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

  • f32021921d33Revision changes
    • warning

      removed the request property

    • warning

      removed the optional property from the response with the status