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

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

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.