> ## Documentation Index > Fetch the complete documentation index at: https://docs.nebius.com/llms.txt > Use this file to discover all available pages before exploring further. # List > Retrieves a list of Devlabs. ## OpenAPI ````yaml https://api.nebius.cloud/openapi.json get /ai/v1/devlabs openapi: 3.0.3 info: title: Nebius API version: version not set servers: - url: https://api.nebius.cloud security: - bearerAuth: [] tags: - name: nebius.ai.v1.DevlabService - name: nebius.ai.v1.EndpointService - name: nebius.ai.v1.JobService - name: nebius.applications.v1alpha1.K8sReleaseService - name: nebius.applications.v1alpha1.VmAppTemplateService - name: nebius.audit.v2.AuditEventExportService - name: nebius.audit.v2.AuditEventService - name: nebius.billing.v1.CalculatorService - name: nebius.billing.v1alpha1.CalculatorService - name: nebius.billing.v1alpha1.OneTimeExportService - name: nebius.capacity.v1.CapacityAllowanceService - name: nebius.capacity.v1.CapacityBlockGroupService - name: nebius.capacity.v1.CapacityIntervalService - name: nebius.capacity.v1.ResourceAdviceService - name: nebius.compute.v1.DiskService - name: nebius.compute.v1.DiskSnapshotService - name: nebius.compute.v1.FilesystemService - name: nebius.compute.v1.GpuClusterService - name: nebius.compute.v1.ImageService - name: nebius.compute.v1.InstanceService - name: nebius.compute.v1.MaintenanceService - name: nebius.compute.v1.NVLInstanceGroupService - name: nebius.compute.v1.NodeService - name: nebius.compute.v1.PlatformService - name: nebius.dns.v1.RecordService - name: nebius.dns.v1.ZoneService - name: nebius.iam.v1.AccessKeyService - name: nebius.iam.v1.AccessPermitService - name: nebius.iam.v1.AuthPublicKeyService - name: nebius.iam.v1.FederatedCredentialsService - name: nebius.iam.v1.FederationCertificateService - name: nebius.iam.v1.FederationService - name: nebius.iam.v1.GroupMembershipService - name: nebius.iam.v1.GroupService - name: nebius.iam.v1.InvitationService - name: nebius.iam.v1.ProfileService - name: nebius.iam.v1.ProjectService - name: nebius.iam.v1.ServiceAccountService - name: nebius.iam.v1.SessionManagementService - name: nebius.iam.v1.StaticKeyService - name: nebius.iam.v1.TenantService - name: nebius.iam.v1.TenantUserAccountService - name: nebius.iam.v1.TenantUserAccountWithAttributesService - name: nebius.iam.v2.AccessKeyService - name: nebius.iam.v2.ProjectService - name: nebius.iam.v2.TenantService - name: nebius.kms.v1.AsymmetricCryptoService - name: nebius.kms.v1.AsymmetricKeyService - name: nebius.kms.v1.SymmetricCryptoService - name: nebius.kms.v1.SymmetricKeyService - name: nebius.logging.agentmanager.v1.VersionService - name: nebius.logging.v1.LogExportService - name: nebius.maintenance.v1alpha1.MaintenanceService - name: nebius.mk8s.v1.ClusterService - name: nebius.mk8s.v1.NodeGroupService - name: nebius.mk8s.v1alpha1.ClusterService - name: nebius.mk8s.v1alpha1.NodeGroupService - name: nebius.monitoring.v1.RecordingRuleService - name: nebius.msp.mlflow.v1alpha1.ClusterService - name: nebius.msp.postgresql.v1alpha1.BackupService - name: nebius.msp.postgresql.v1alpha1.ClusterService - name: nebius.mysterybox.v1.PayloadService - name: nebius.mysterybox.v1.SecretService - name: nebius.mysterybox.v1.SecretVersionService - name: nebius.quotas.v1.QuotaAllowanceService - name: nebius.registry.v1.ArtifactService - name: nebius.registry.v1.RegistryService - name: nebius.storage.v1.BucketService - name: nebius.storage.v1.InventoryService - name: nebius.storage.v1.TransferService - name: nebius.storage.v1alpha1.TransferService - name: nebius.tunnel.v1.TunnelService - name: nebius.vpc.v1.AllocationService - name: nebius.vpc.v1.NetworkService - name: nebius.vpc.v1.PoolService - name: nebius.vpc.v1.RouteService - name: nebius.vpc.v1.RouteTableService - name: nebius.vpc.v1.SecurityGroupService - name: nebius.vpc.v1.SecurityRuleService - name: nebius.vpc.v1.SubnetService - name: nebius.vpc.v1.TargetGroupService - name: nebius.vpc.v1alpha1.AllocationService - name: nebius.vpc.v1alpha1.NetworkService - name: nebius.vpc.v1alpha1.PoolService - name: nebius.vpc.v1alpha1.ScopeService - name: nebius.vpc.v1alpha1.SubnetService paths: /ai/v1/devlabs: get: tags: - nebius.ai.v1.DevlabService summary: List description: Retrieves a list of Devlabs. operationId: DevlabService_List parameters: - description: The ID of the project that contains the Devlabs. in: query name: parentId required: true schema: type: string - description: >- The maximum number of Devlabs to return. The default and maximum are 100. Values outside the range 1 to 100 use the default. in: query name: pageSize schema: format: int64 type: string - description: >- The next_page_token from the previous response. Use an empty string for the first page. Keep parent_id unchanged when you request the next page. in: query name: pageToken schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/nebius.ai.v1.ListDevlabsResponse' description: A successful response. components: schemas: nebius.ai.v1.ListDevlabsResponse: description: A page of Devlabs from a project. properties: items: description: >- The Devlabs in this page. The list can contain fewer items than page_size. items: $ref: '#/components/schemas/nebius.ai.v1.Devlab' type: array nextPageToken: description: >- The token for the next page. An empty string indicates the end of the list. type: string type: object nebius.ai.v1.Devlab: description: >- Represents an interactive development environment backed by Serverless infrastructure. properties: metadata: allOf: - $ref: '#/components/schemas/nebius.common.v1.ResourceMetadata' description: The metadata of the Devlab. spec: allOf: - $ref: '#/components/schemas/nebius.ai.v1.DevlabSpec' description: The configuration of the Devlab. status: allOf: - $ref: '#/components/schemas/nebius.ai.v1.DevlabStatus' description: The current status of the Devlab. readOnly: true type: object nebius.common.v1.ResourceMetadata: description: Common resource metadata. properties: createdAt: description: Timestamp indicating when the resource was created. format: date-time readOnly: true type: string id: description: Identifier for the resource, unique for its resource type. type: string labels: additionalProperties: type: string description: Labels associated with the resource. type: object name: description: Human readable name for the resource. type: string parentId: description: Identifier of the parent resource to which the resource belongs. type: string resourceVersion: description: >- Version of the resource for safe concurrent modifications and consistent reads. Positive and monotonically increases on each resource spec change (but *not* on each change of the resource's container(s) or status). Service allows zero value or current. format: int64 type: string updatedAt: description: Timestamp indicating when the resource was last updated. format: date-time readOnly: true type: string required: - parentId type: object nebius.ai.v1.DevlabSpec: description: DevlabSpec defines an interactive workload that will be run. properties: args: description: The arguments to pass to the entrypoint command. type: string authTokenMysteryboxSecret: allOf: - $ref: '#/components/schemas/nebius.ai.v1.DevlabSpec.MysteryBoxSecretRef' description: >- The MysteryBox secret that contains the authentication token under the `AUTH_TOKEN` payload key. This field enables an authentication proxy for the Devlab's HTTP ports. The proxy rejects requests without an `Authorization: Bearer ` header that contains the matching token. If absent, Serverless does not add this bearer-token check. containerCommand: description: The entrypoint command for the Devlab's container. type: string disk: allOf: - $ref: '#/components/schemas/nebius.ai.v1.DevlabSpec.DiskSpec' description: Disk spec for the main disk of the Devlab runtime VM. environmentVariables: description: Specifies the environment variables for the Devlab's container. items: $ref: '#/components/schemas/nebius.ai.v1.DevlabSpec.EnvironmentVariable' type: array image: description: |- The Docker image to use for the Devlab's container. Required unless `template` is set: the template declares the image. type: string injectedFiles: description: >- Small config files injected into the container before the user process starts. Intended for configs, not datasets. Read methods return target paths. File content is returned only by Get with view SECRET. items: $ref: '#/components/schemas/nebius.ai.v1.DevlabSpec.FileInjection' type: array platform: description: Compute platform that the Devlab will be run on. type: string ports: description: Specifies the ports that the Devlab exposes. items: $ref: '#/components/schemas/nebius.ai.v1.DevlabSpec.Port' type: array preset: description: Compute preset that the Devlab will be run on. type: string primaryRoute: allOf: - $ref: '#/components/schemas/nebius.ai.v1.DevlabSpec.PrimaryRoute' description: |- Primary web route exposed through the managed HTTPS endpoint. Required unless `template` is set: the template declares the primary web UI port. publicIp: description: Whether to assign a public IP to the Devlab runtime VM. type: boolean registryCredentials: allOf: - $ref: '#/components/schemas/nebius.ai.v1.DevlabSpec.RegistryCredentials' description: Registry credentials for private Docker registry. shmSizeBytes: description: Shared memory size in bytes for the Devlab's container. format: int64 type: string sshAuthorizedKeys: description: Public keys to be authorized for SSH access to the Devlab. items: type: string type: array subnetId: description: Subnet ID where the Devlab will be deployed. type: string template: allOf: - $ref: '#/components/schemas/nebius.ai.v1.DevlabSpec.Template' description: >- Template that defines the Devlab's container. When set, the template declares the container shape: image, entrypoint command, arguments, working directory, ports, optional shared memory size, the primary web route, and the default workspace path. The spec must leave image, container command, arguments, working directory, and primary route empty. Environment variables and ports extend the template-declared ones, `workspace.container_path` may override the template default, and `shm_size_bytes` may be set only when the template leaves it unset. The template is consumed at creation time: read methods return the rendered container shape instead of the template reference. volumes: description: Extra volumes to be mounted into the Devlab container. items: $ref: '#/components/schemas/nebius.ai.v1.DevlabSpec.VolumeMount' type: array workingDir: description: The working directory for the Devlab's container. type: string workspace: allOf: - $ref: '#/components/schemas/nebius.ai.v1.DevlabSpec.Workspace' description: Primary workspace storage for user state. required: - platform - preset - disk - subnetId - workspace type: object nebius.ai.v1.DevlabStatus: description: DevlabStatus represents the status of a Devlab. properties: instances: description: Status of individual Devlab runtime instances. items: $ref: '#/components/schemas/nebius.ai.v1.DevlabInstanceStatus' type: array privateEndpoints: description: Private endpoints to access the workload. items: type: string type: array publicEndpoints: description: >- Managed HTTPS/TLS URLs the workload is reachable at, one per routable port. Populated only while the Devlab is RUNNING and its managed tunnel is ready; empty otherwise. The URLs are not bearer secrets — Tunna/IAM authorizes access on use — so they are returned to any caller that may read the Devlab. items: type: string type: array state: allOf: - $ref: '#/components/schemas/nebius.ai.v1.DevlabStatus.State' description: State of the Devlab. stateDetails: allOf: - $ref: '#/components/schemas/nebius.ai.v1.DevlabStateDetails' description: Details of the Devlab's state. type: object nebius.ai.v1.DevlabSpec.MysteryBoxSecretRef: description: Reference to a MysteryBox secret. properties: secretId: description: MysteryBox secret ID. type: string versionId: description: MysteryBox secret version ID. type: string type: object nebius.ai.v1.DevlabSpec.DiskSpec: properties: sizeBytes: description: Disk size in bytes. format: int64 type: string type: allOf: - $ref: '#/components/schemas/nebius.compute.v1.DiskSpec.DiskType' description: Disk type. required: - type type: object nebius.ai.v1.DevlabSpec.EnvironmentVariable: description: >- EnvironmentVariable defines an environment variable for the Devlab's container. properties: mysteryboxSecret: allOf: - $ref: '#/components/schemas/nebius.ai.v1.DevlabSpec.MysteryBoxSecretRef' description: >- Secret storing the environment variable value. The value is read from the payload entry whose key matches the variable name, or the first entry when no such key exists. name: description: The name of the environment variable. type: string value: description: |- Environment variable value. The unmasked value is returned only by Get with view SECRET. type: string required: - name type: object nebius.ai.v1.DevlabSpec.FileInjection: description: FileInjection materializes a small file inside the container at launch. properties: containerPath: description: |- Absolute path inside the container where the content is written. Must be a clean absolute path: root, trailing slashes, empty path segments, "." and ".." are not allowed. type: string content: description: |- File content. On create, must contain between 1 byte and 64 KiB (one mystery box secret payload). Returned only by Get with view SECRET. format: byte type: string required: - containerPath type: object nebius.ai.v1.DevlabSpec.Port: properties: containerPort: description: Container port. format: int32 type: integer hostPort: description: |- Host port. Set to 0 to use the same value as container_port. format: int32 type: integer protocol: allOf: - $ref: '#/components/schemas/nebius.ai.v1.DevlabSpec.Port.Protocol' description: Port's protocol. required: - protocol type: object nebius.ai.v1.DevlabSpec.PrimaryRoute: properties: containerPort: description: Container port that serves the primary web UI. format: int32 type: integer type: object nebius.ai.v1.DevlabSpec.RegistryCredentials: properties: mysteryboxSecretVersion: description: |- Secret version storing the registry credentials. Must have keys "REGISTRY_USERNAME" and "REGISTRY_PASSWORD". type: string type: object nebius.ai.v1.DevlabSpec.Template: description: Reference to a VM app template the Devlab's container is rendered from. properties: id: description: VM app template ID. type: string inputFieldValues: additionalProperties: {} description: >- The values for the template's input fields, keyed by each TemplateInputField.id. VmAppTemplateService.Get and List return these field definitions in VmAppTemplate.status.input_fields. Each value must match its field's type: - STRING: string_value. The value must satisfy the template's pattern, options, or unit format. - INTEGER: number_value with an integer value within the template's bounds. - BOOLEAN: bool_value. - MYSTERYBOX_SECRET_VERSION: string_value with the secret version ID. null_value and absent entries both omit the input. Required inputs cannot be omitted. Optional inputs use the defaults from the template's input definition. Explicit false, 0, and empty strings are values, not omitted inputs. The template's validation still applies. Object and list values are not supported. Unknown field IDs have no effect. Read methods do not return this map. type: object required: - id type: object nebius.ai.v1.DevlabSpec.VolumeMount: description: VolumeMount represents an extra volume mount for the Devlab container. properties: containerPath: description: |- Path inside the Devlab container where the volume is mounted. Must be a clean absolute path: root, trailing slashes, empty path segments, "." and ".." are not allowed. type: string mode: allOf: - $ref: '#/components/schemas/nebius.ai.v1.DevlabSpec.VolumeMount.Mode' description: Mount mode. s3Config: $ref: '#/components/schemas/nebius.ai.v1.DevlabSpec.VolumeMount.S3Config' source: description: >- Source of the volume mount. Can be a name or an ID of Nebius Storage bucket or filesystem, or an S3 URI (e.g. "s3://bucket-name") when using external S3 storage. type: string sourcePath: description: |- Path inside the source volume. Optional. type: string required: - source - containerPath - mode type: object nebius.ai.v1.DevlabSpec.Workspace: properties: containerPath: description: >- Path inside the Devlab container where the workspace is mounted. Must be a clean absolute path: root, trailing slashes, empty path segments, "." and ".." are not allowed. Required unless the Devlab is created from a template: the template declares the default workspace path, and a non-empty value overrides it. type: string type: object nebius.ai.v1.DevlabInstanceStatus: description: DevlabInstanceStatus represents the status of a Devlab runtime instance. properties: computeInstanceId: description: ID of the compute instance running the Devlab. type: string computeInstanceState: allOf: - $ref: >- #/components/schemas/nebius.compute.v1.InstanceStatus.InstanceState description: The current state of the compute instance. privateIp: description: Private IP address of the instance. type: string publicIp: description: Public IP address of the instance. type: string state: allOf: - $ref: '#/components/schemas/nebius.ai.v1.DevlabInstanceStatus.State' description: The current state of the Devlab's workload. type: object nebius.ai.v1.DevlabStatus.State: default: STATE_UNSPECIFIED description: |- Devlab state. - STATE_UNSPECIFIED: The service did not report the Devlab's state. - PROVISIONING: The Devlab is creating resources. - STARTING: The Devlab is being started. - RUNNING: The Devlab is running. - STOPPING: The Devlab is being stopped. - DELETING: The Devlab is being deleted. - STOPPED: The Devlab has been stopped. - FAILED: The Devlab has failed. - ERROR: The Devlab encountered an error. - IMAGE_PULLING: The Devlab is pulling an image (STARTING -> IMAGE_PULLING -> RUNNING). enum: - STATE_UNSPECIFIED - PROVISIONING - STARTING - RUNNING - STOPPING - DELETING - STOPPED - FAILED - ERROR - IMAGE_PULLING type: string nebius.ai.v1.DevlabStateDetails: description: Devlab state details. properties: code: description: Short state description. type: string message: description: Detailed human-readable description. type: string type: object nebius.compute.v1.DiskSpec.DiskType: default: UNSPECIFIED description: >- the list of available types will be clarified later, it is not final version enum: - UNSPECIFIED - NETWORK_SSD - NETWORK_HDD - NETWORK_SSD_NON_REPLICATED - NETWORK_SSD_IO_M3 type: string nebius.ai.v1.DevlabSpec.Port.Protocol: default: PROTOCOL_UNSPECIFIED description: |- Represents protocol of the Devlab's port which will be exposed. - PROTOCOL_UNSPECIFIED: No protocol selected. Specify HTTP, TCP, or UDP. - HTTP: HTTP protocol. - TCP: TCP protocol. - UDP: UDP protocol. enum: - PROTOCOL_UNSPECIFIED - HTTP - TCP - UDP type: string nebius.ai.v1.DevlabSpec.VolumeMount.Mode: default: MODE_UNSPECIFIED description: |- Mode that will be used to mount the volume. - MODE_UNSPECIFIED: No mount mode selected. Specify READ_WRITE or READ_ONLY. - READ_WRITE: Read-write mode. - READ_ONLY: Read-only mode. enum: - MODE_UNSPECIFIED - READ_WRITE - READ_ONLY type: string nebius.ai.v1.DevlabSpec.VolumeMount.S3Config: description: |- Config for accessing an external S3-compatible storage. The bucket name is specified in the `source` field as an S3 URI. properties: endpoint: description: S3-compatible endpoint URL (e.g. "https://s3.amazonaws.com"). type: string mysteryboxSecret: allOf: - $ref: '#/components/schemas/nebius.ai.v1.DevlabSpec.MysteryBoxSecretRef' description: Reference to a MysteryBox secret containing S3 credentials. region: description: S3 region. type: string required: - endpoint - region - mysteryboxSecret type: object nebius.compute.v1.InstanceStatus.InstanceState: default: UNSPECIFIED enum: - UNSPECIFIED - CREATING - UPDATING - STARTING - RUNNING - STOPPING - STOPPED - DELETING - ERROR type: string nebius.ai.v1.DevlabInstanceStatus.State: default: STATE_UNSPECIFIED description: |- Devlab instance state. - STATE_UNSPECIFIED: The service did not report the instance's state. - PROVISIONING: The Devlab is creating resources. - STARTING: The Devlab is being started. - RUNNING: The Devlab is running. - STOPPING: The Devlab is being stopped. - DELETING: The Devlab is being deleted. - STOPPED: The Devlab has been stopped. - FAILED: The Devlab has failed. - ERROR: The Devlab encountered an error. - IMAGE_PULLING: The Devlab is pulling an image (STARTING -> IMAGE_PULLING -> RUNNING). enum: - STATE_UNSPECIFIED - PROVISIONING - STARTING - RUNNING - STOPPING - DELETING - STOPPED - FAILED - ERROR - IMAGE_PULLING type: string securitySchemes: bearerAuth: description: The Authorization header expects a Bearer token. scheme: bearer type: http ````