DocumentationAPI Reference

Pods API

Spin up compute in seconds. The Pods API lets you create, list, pause, resume, and delete GPU-backed containers across Yotta’s distributed cloud.

Versioning All endpoints are currently under the v1 namespace (e.g., /openapi/v1/...). Backward-compatible enhancements may be added to v1. Breaking changes will ship under a new version (e.g., v2).

Create Pod

Endpoint: /openapi/v1/pods/create

Method: POST Description: Launches a new compute Pod on the Yotta platform using a container image.

Params

Name
Location
Type
Required
Description

x-api-key

header

string

Yes

none

body

body

OpenapiPodCreateRequest

No

none

Request Body (JSON)

Field
Type
Required
Description

image

string

✓

Docker image name (e.g., yottalabsai/pytorch:2.8.0-py3.11-cuda12.8.1-cudnn-devel-ubuntu22.04-2025050802).

gpuType

string

✓

GPU type identifier (e.g., NVIDIA_L4_24G, NVIDIA_H100_80GB_HBM3_80G, NVIDIA_GeForce_RTX_4090_24G, NVIDIA_GeForce_RTX_5090_32G).

gpuCount

integer

✓

Number of GPUs to attach to the Pod.

environmentVars

KeyValuePair[]

Environment variables (e.g., Jupyter password).

expose

ExposePort[]

Ports to expose (e.g., SSH on 22).

imagePublicType

enum

One of OFFICIAL, CUSTOM, PUBLIC, PRIVATE. Use PRIVATE with registry credentials.

imageRegistryUsername

string

Username for private registry (when imagePublicType = PRIVATE).

imageRegistryToken

string

Token/password for private registry (when imagePublicType = PRIVATE).

initializationCommand

string

Command to run on startup (e.g., "sshd &").

See short model snippets at the end of this page, and full schemas in Common Models.

Example (Public Image) — curl

curl -X POST 'https://api.yottalabs.ai/openapi/v1/pods/create' \
  -H 'x-api-key: <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "image": "yottalabsai/pytorch:2.8.0-py3.11-cuda12.8.1-cudnn-devel-ubuntu22.04-2025050802",
    "gpuType": "NVIDIA_L4_24G",
    "gpuCount": 1,
    "environmentVars": [
      { "key": "JUPYTER_PASSWORD", "value": "your_password" }
    ],
    "expose": [
      { "port": 22, "protocol": "SSH" }
    ]
  }'

Example (Public Image) — Python (requests)

import requests

url = "https://api.yottalabs.ai/openapi/v1/pods/create"
headers = {"x-api-key": "<YOUR_API_KEY>", "Content-Type": "application/json"}
payload = {
    "image": "yottalabsai/pytorch:2.8.0-py3.11-cuda12.8.1-cudnn-devel-ubuntu22.04-2025050802",
    "gpuType": "NVIDIA_L4_24G",
    "gpuCount": 1,
    "environmentVars": [{"key": "JUPYTER_PASSWORD", "value": "your_password"}],
    "expose": [{"port": 22, "protocol": "SSH"}],
}
resp = requests.post(url, headers=headers, json=payload, timeout=60)
print(resp.json())

Example (Private Image) — curl

curl -X POST 'https://api.yottalabs.ai/openapi/v1/pods/create' \
  -H 'x-api-key: <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "imagePublicType": "PRIVATE",
    "imageRegistryUsername": "your_registry_user",
    "imageRegistryToken": "dckr_pat_xxx",
    "image": "yourorg/your-private-image:tag",
    "gpuType": "NVIDIA_L4_24G",
    "gpuCount": 1,
    "initializationCommand": "sshd &",
    "expose": [
      { "port": 22, "protocol": "SSH" }
    ]
  }'

Example (Private Image) — Python (requests)

import requests

url = "https://api.yottalabs.ai/openapi/v1/pods/create"
headers = {"x-api-key": "<YOUR_API_KEY>", "Content-Type": "application/json"}
payload = {
    "imagePublicType": "PRIVATE",
    "imageRegistryUsername": "your_registry_user",
    "imageRegistryToken": "dckr_pat_xxx",
    "image": "yourorg/your-private-image:tag",
    "gpuType": "NVIDIA_L4_24G",
    "gpuCount": 1,
    "initializationCommand": "sshd &",
    "expose": [{"port": 22, "protocol": "SSH"}],
}
resp = requests.post(url, headers=headers, json=payload, timeout=60)
print(resp.json())

Responses

HTTP Status Code
Response Code
Meaning
Description
Data schema

200

10000

Request OK

create success

ResultVoid

400

Bad Request

Bad Request

ResultObject

500

Internal Server Error

Internal Server Error

ResultObject

Response Example (200)

{
  "message": "success",
  "code": 10000,
  "data": 43264375788654
}

List Pods

Endpoint: /openapi/v1/pods/list

Method: GET Description: Returns all Pods owned by the current organization. Supports multi-value filtering.

Params

Name
Location
Type
Required
Description

regionList

query

array<string>

No

Filter by regions. e.g. regionList=ap-southeast-1&regionList=us-west-1

statusList

query

array<int>

No

Filter by status codes. e.g. statusList=1&statusList=3

x-api-key

header

string

Yes

API key token

Note: Both regionList and statusList are multi-value query parameters. Send the parameter multiple times to specify multiple values. The server matches any of the provided values (logical OR).

statusList Values

Supported status codes and their meanings:

Value
Name
Meaning

0

INITIALIZE

Initializing: created and preparing resources/configuration.

1

RUNNING

Running: available and serving traffic.

2

PAUSING

Pausing: entering shutdown flow; may stop accepting new work.

3

PAUSED

Paused: unavailable to serve; resources retained and can be resumed.

4

TERMINATING

Terminating: tearing down resources and shutting down.

Validation Rules

  • When statusList is omitted, no status filter is applied (all statuses are returned).

Example — curl

curl -X GET 'https://api.yottalabs.ai/openapi/v1/pods/list?statusList=RUNNING&statusList=PAUSED&regionList=gke-dev-us-west-1' \
  -H 'x-api-key: <YOUR_API_KEY>'

Example — Python

import requests

url = "https://api.yottalabs.ai/openapi/v1/pods/list"
headers = {"x-api-key": "<YOUR_API_KEY>"}
params = [
    ("statusList", "RUNNING"),
    ("statusList", "PAUSED"),
    ("regionList", "us-east-2"),
]
resp = requests.get(url, headers=headers, params=params, timeout=30)
print(resp.json())

Responses

HTTP Status Code
Response Code
Meaning
Description
Data schema

200

10000

Request OK

create success

ResultListOpenapiPodDetailResponse

400

Bad Request

Bad Request

ResultObject

500

Internal Server Error

Internal Server Error

ResultObject

Response Example (200)

{
  "message": "success",
  "code": 10000,
  "data": [{
    "id": "331864222263676928",
    "orgId": "217646376996249600",
    "applicantId": "217646376987860992",
    "podName": "Test_from_SDK",
    "imageId": "219419172892971011",
    "officialImage": "CUSTOM",
    "imagePublicType": "PUBLIC",
    "image": "yottalabsai/pytorch:2.8.0-py3.11-cuda12.8.1-cudnn-devel-ubuntu22.04-2025050802",
    "imageRegistryUsername": null,
    "resourceType": "GPU",
    "gpuType": "NVIDIA_L4_24G",
    "gpuDisplayName": "L4",
    "gpuCount": 1,
    "singleCardVramInGb": 24,
    "singleCardRamInGb": 10,
    "singleCardVcpu": 3,
    "location": "OR",
    "region": "gke-dev-us-west-1",
    "cloudType": "SECURE",
    "containerVolumeInGb": 252,
    "persistentVolumeInGb": 0,
    "persistentMountPath": null,
    "networkUploadMbps": 1258.2912,
    "networkDownloadMbps": 1761.60768,
    "diskReadSpeedMbps": 2516.5824,
    "diskWriteSpeedMbps": 5872.0256,
    "singleCardPrice": 0.6,
    "persistentVolumePrice": 0.00005,
    "containerVolumePrice": 0.00005,
    "initializationCommand": "",
    "environmentVars": [{
      "key": "JUPYTER_PASSWORD",
      "value": "9f2375dc-277b-4550-add9-563ad23973a5"
    }],
    "expose": [{
      "port": 22,
      "proxyPort": 32002,
      "protocol": "SSH",
      "host": "34.19.26.12",
      "healthy": true,
      "ingressUrl": "ssh [email protected] -p 32002 -i <private key file>",
      "serviceName": "SSH Port"
    }],
    "sshCmd": "",
    "status": "TERMINATED",
      "createdAt": "2025-07-04 10:29:56",
      "updatedAt": "2025-07-04 10:48:13"
  }]
}

Pause Pod

Endpoint: /openapi/v1/pods/pause/{podId}

Method: POST Description: Pauses a running Pod to reduce cost.

Params

Name
Location
Type
Required
Description

podId

path

string

Yes

The Pod ID to pause.

x-api-key

header

string

Yes

none

Example — curl

curl -X POST 'https://api.yottalabs.ai/openapi/v1/pods/pause/331864222263676928' \
  -H 'x-api-key: <YOUR_API_KEY>'

Example — Python

import requests

pod_id = "331864222263676928"
url = f"https://api.yottalabs.ai/openapi/v1/pods/pause/{pod_id}"
headers = {"x-api-key": "<YOUR_API_KEY>"}
resp = requests.post(url, headers=headers, timeout=30)
print(resp.json())

Responses

HTTP Status Code
Response Code
Meaning
Description
Data schema

200

10000

Request OK

pause success

ResultVoid

400

Bad Request

Bad Request

ResultObject

500

Internal Server Error

Internal Server Error

ResultObject

Response Example (200)

{
  "message": "success",
  "code": 10000,
  "data": null
}

Resume Pod

Endpoint: /openapi/v1/pods/resume/{podId}

Method: POST Description: Resumes a previously paused Pod.

Params

Name
Location
Type
Required
Description

podId

path

string

Yes

The Pod ID to resume.

x-api-key

header

string

Yes

none

Example — curl

curl -X POST 'https://api.yottalabs.ai/openapi/v1/pods/resume/331864222263676928' \
  -H 'x-api-key: <YOUR_API_KEY>'

Example — Python

import requests

pod_id = "331864222263676928"
url = f"https://api.yottalabs.ai/openapi/v1/pods/resume/{pod_id}"
headers = {"x-api-key": "<YOUR_API_KEY>"}
resp = requests.post(url, headers=headers, timeout=30)
print(resp.json())

Responses

HTTP Status Code
Response Code
Meaning
Description
Data schema

200

10000

Request OK

resume success

ResultVoid

400

Bad Request

Bad Request

ResultObject

500

Internal Server Error

Internal Server Error

ResultObject

Response Example (200)

{
  "message": "success",
  "code": 10000,
  "data": null
}

Delete Pod

Endpoint: /openapi/v1/pods/{podId}

Method: DELETE Description: Permanently deletes a Pod.

Irreversible — This action permanently removes the Pod and its runtime. Ensure data you need is persisted externally before deleting.

Params

Name
Location
Type
Required
Description

podId

path

string

Yes

The Pod ID to delete.

x-api-key

header

string

Yes

none

Example — curl

curl -X DELETE 'https://api.yottalabs.ai/openapi/v1/pods/331864222263676928' \
  -H 'x-api-key: <YOUR_API_KEY>'

Example — Python

import requests

pod_id = "331864222263676928"
url = f"https://api.yottalabs.ai/openapi/v1/pods/{pod_id}"
headers = {"x-api-key": "<YOUR_API_KEY>"}
resp = requests.delete(url, headers=headers, timeout=30)
print(resp.json())

Responses

HTTP Status Code
Response Code
Meaning
Description
Data schema

200

10000

Request OK

delete success

ResultVoid

400

Bad Request

Bad Request

ResultObject

500

Internal Server Error

Internal Server Error

ResultObject

Response Examples (200)

{
  "message": "success",
  "code": 10000,
  "data": null
}

Best Practices

  • Secure images: Use PRIVATE images with registry credentials when needed.

  • Harden access: Set a strong JUPYTER_PASSWORD (or disable public endpoints you don’t need).

  • Lifecycle hygiene: Pause or delete idle Pods to optimize cost.

  • Automate flows: Use List → Pause/Resume in CI/agents to orchestrate workloads.

PreviousAPI SpecNextData Model

Last updated

Was this helpful?