From d6b3c522f4d2e40e3132148abb3152c8105a2e5e Mon Sep 17 00:00:00 2001 From: lgunreddi Date: Thu, 25 Jun 2026 10:13:54 -0400 Subject: [PATCH 01/41] New API v2 - overview.mdx --- api-reference-v2/overview.mdx | 134 ++++++++++++++++++++++++++++++++++ 1 file changed, 134 insertions(+) create mode 100644 api-reference-v2/overview.mdx diff --git a/api-reference-v2/overview.mdx b/api-reference-v2/overview.mdx new file mode 100644 index 00000000..5f72a110 --- /dev/null +++ b/api-reference-v2/overview.mdx @@ -0,0 +1,134 @@ +--- +title: "REST API v2" +sidebarTitle: "Overview" +description: "Programmatically manage Runpod resources using the REST API v2." +--- + + + REST API v2 is currently in open beta. Endpoints and behavior may change before general availability. + + +The Runpod REST API v2 provides programmatic access to your Runpod resources over standard HTTP. Use it to create and manage Pods, query Serverless endpoints, provision storage, and retrieve billing data — without using the console. + +## Base URL + +``` +https://rest.runpod.io/v2 +``` + +## Authentication + +All requests require a Runpod API key passed as a Bearer token in the `Authorization` header. + +```bash +Authorization: Bearer YOUR_RUNPOD_API_KEY +``` + +To get your API key, go to **Settings → API Keys** in the [Runpod console](https://console.runpod.io). + +## Quick start + +Here's a simple request to list your Pods: + +```bash cURL +curl --request GET \ + --url https://rest.runpod.io/v2/pods \ + --header 'Authorization: Bearer YOUR_RUNPOD_API_KEY' +``` + +```python Python +import requests + +url = "https://rest.runpod.io/v2/pods" +headers = {"Authorization": "Bearer YOUR_RUNPOD_API_KEY"} + +response = requests.get(url, headers=headers) +print(response.json()) +``` + +```javascript JavaScript +const response = await fetch("https://rest.runpod.io/v2/pods", { + headers: { + Authorization: "Bearer YOUR_RUNPOD_API_KEY", + }, +}); +const data = await response.json(); +console.log(data); +``` + +## Available resources + +| Resource | Description | +|---|---| +| **Pods** | Create, start, stop, and delete GPU Pods | +| **Endpoints** | Read Serverless endpoint configuration and status | +| **Network volumes** | Create and manage persistent storage | +| **Templates** | Save and reuse Pod configurations | +| **Container registry auths** | Connect to private Docker registries | +| **Billing** | Retrieve usage and billing history | + + + Endpoint management (create, update, delete) is not yet available in REST API v2. Use the [GraphQL API](/api-reference/overview) for full endpoint control in the meantime. + + +## OpenAPI specification + +Retrieve the full OpenAPI spec for client generation or tooling: + +```bash +curl --request GET \ + --url https://rest.runpod.io/v2/openapi.json \ + --header 'Authorization: Bearer YOUR_RUNPOD_API_KEY' +``` + +## What's new in v2 + +REST API v2 is a redesigned, REST-native interface replacing the v1 API. Key improvements: + +- Cleaner, more consistent resource paths +- Standard HTTP status codes and error responses +- OpenAPI 3.0 spec for easy client generation +- Improved validation and error messages + +## Differences from v1 + +| | v1 | v2 | +|---|---|---| +| Base URL | `rest.runpod.io/v1` | `rest.runpod.io/v2` | +| Spec format | OpenAPI 3.0 | OpenAPI 3.0 | +| Endpoint management | Full CRUD | Read-only (beta) | +| Authentication | Bearer token | Bearer token | + +## Error responses + +The API returns standard HTTP status codes: + +| Code | Meaning | +|---|---| +| `200` | Success | +| `400` | Bad request — check your request body or parameters | +| `401` | Unauthorized — missing or invalid API key | +| `404` | Resource not found | +| `422` | Validation error — invalid field values | +| `429` | Rate limit exceeded | +| `500` | Internal server error | + +Error responses include a JSON body with details: + +```json +{ + "detail": "missing bearer token", + "status": 401, + "title": "Unauthorized" +} +``` + +## Next steps + +Explore the interactive API reference to test endpoints directly in your browser: + +- [Pods](/api-reference/v2/pods) +- [Endpoints](/api-reference/v2/endpoints) +- [Network volumes](/api-reference/v2/network-volumes) +- [Templates](/api-reference/v2/templates) +- [Billing](/api-reference/v2/billing) From 252b9827df867a5c4c1e3fb031368d0e089fb51a Mon Sep 17 00:00:00 2001 From: lgunreddi Date: Thu, 25 Jun 2026 10:17:08 -0400 Subject: [PATCH 02/41] Update docs.json --- docs.json | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs.json b/docs.json index a70e9368..5f09df05 100644 --- a/docs.json +++ b/docs.json @@ -511,6 +511,17 @@ } ] }, + { + "tab": "API v2", + "groups": [ + { + "group": "REST API v2", + "pages": [ + "api-reference-v2/overview" + ] + } + ] + }, { "tab": "Models", "groups": [ From 6feef16616c8c47b93d8c661eb3640d43ff834c3 Mon Sep 17 00:00:00 2001 From: lgunreddi Date: Thu, 25 Jun 2026 14:37:53 -0400 Subject: [PATCH 03/41] Add files via upload --- api-reference-v2/openapi.json | 3529 +++++++++++++++++++++++++++++++++ 1 file changed, 3529 insertions(+) create mode 100644 api-reference-v2/openapi.json diff --git a/api-reference-v2/openapi.json b/api-reference-v2/openapi.json new file mode 100644 index 00000000..2b03fb0f --- /dev/null +++ b/api-reference-v2/openapi.json @@ -0,0 +1,3529 @@ +{ + "openapi": "3.0.3", + "info": { + "title": "RunPod REST API", + "version": "2.0.0", + "description": "RunPod public REST API — v2" + }, + "servers": [ + { + "url": "/", + "description": "Current server" + } + ], + "security": [ + { + "bearerAuth": [] + } + ], + "components": { + "securitySchemes": { + "bearerAuth": { + "type": "http", + "scheme": "bearer", + "bearerFormat": "RunPod API Key" + } + }, + "schemas": { + "ContainerConfig": { + "type": "object", + "description": "Reusable container configuration shared across templates, pods, and endpoints. Adding a field here automatically propagates to all three resources.\n", + "properties": { + "image": { + "type": "string", + "description": "Docker image reference", + "example": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1" + }, + "args": { + "type": "string", + "description": "Arguments passed to the container entrypoint", + "example": "" + }, + "disk": { + "type": "integer", + "minimum": 1, + "description": "Container disk in GB (ephemeral, wiped on restart)", + "example": 50 + }, + "ports": { + "type": "array", + "description": "Exposed ports, formatted as port/protocol", + "items": { + "type": "string" + }, + "example": [ + "8888/http", + "22/tcp" + ] + }, + "env": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "Environment variables as key-value pairs", + "example": { + "JUPYTER_PASSWORD": "hunter2" + } + }, + "registry": { + "type": "string", + "nullable": true, + "description": "Container registry credential ID (for private images)", + "example": null + } + } + }, + "Mounts": { + "type": "object", + "additionalProperties": false, + "description": "Storage mounts attached to a pod. At-most-one of `persistent` or\n`network` may be set today (mutually exclusive, enforced at the\nhandler with 400 if both are present). The `network` field is an\narray for forward compatibility with eventual multi-network-volume\nsupport, but `maxItems` is 1 today.\n\nPATCH semantics:\n- Omitting `mounts` or sending `{}` leaves the existing mount\n unchanged.\n- An explicit `network: []` is rejected with 400 (clearing mounts\n is not supported).\n- Mount kind is fixed at create — a PATCH that introduces a kind\n not present at create (persistent on a network pod, network on\n a persistent pod, or any mount on a previously-mountless pod)\n is rejected with 400.\n- The `volumeId` of a network mount is immutable; a PATCH that\n names a different `volumeId` is rejected with 400.\n- Partial mounts are not supported — every mount entry must\n include the full schema (`size` + `path` for persistent,\n `volumeId` + `path` for network). Missing required fields → 422.\n", + "properties": { + "persistent": { + "$ref": "#/components/schemas/PersistentMount" + }, + "network": { + "type": "array", + "maxItems": 1, + "items": { + "$ref": "#/components/schemas/NetworkMount" + } + } + } + }, + "TemplateMounts": { + "type": "object", + "additionalProperties": false, + "description": "Storage mounts attached to a template. Templates support only a\nsingle persistent mount today; any `network` property is rejected\nwith 422 by the schema validator.\n\nPATCH semantics: omitting `mounts` or sending `{}` leaves the\nexisting mount unchanged.\n", + "properties": { + "persistent": { + "$ref": "#/components/schemas/PersistentMount" + } + } + }, + "PersistentMount": { + "type": "object", + "required": [ + "size", + "path" + ], + "additionalProperties": false, + "description": "Host-local persistent storage. Pinned to the pod's host machine — data\ndoes not survive a host failure. Disallowed on CPU pods. Mutually\nexclusive with NetworkMount. Deprecated: prefer NetworkMount for any\ndata you cannot recreate.\n", + "properties": { + "size": { + "type": "integer", + "minimum": 10, + "description": "Host-local persistent storage in GB. Upstream enforces a 10 GB floor.", + "example": 20 + }, + "path": { + "type": "string", + "description": "Mount path inside the container. May be changed via PATCH.", + "example": "/workspace" + } + } + }, + "NetworkMount": { + "type": "object", + "required": [ + "volumeId", + "path" + ], + "additionalProperties": false, + "description": "Reference to a NetworkVolume. Custom paths are honored at runtime on\nboth GPU and CPU pods. The underlying `volumeId` is immutable\npost-create; the mount `path` may be changed via PATCH.\n", + "properties": { + "volumeId": { + "type": "string", + "description": "ID of an existing NetworkVolume in the same data center as the pod.", + "example": "vol_xyz" + }, + "path": { + "type": "string", + "description": "Mount path inside the container. No default — must be specified explicitly.", + "example": "/runpod-volume" + } + } + }, + "GpuConfig": { + "type": "object", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "string", + "description": "GPU type identifier", + "example": "NVIDIA GeForce RTX 4090" + }, + "count": { + "type": "integer", + "minimum": 1, + "default": 1, + "description": "Number of GPUs", + "example": 1 + } + } + }, + "CpuConfig": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "CPU flavor identifier", + "example": "cpu5c" + }, + "count": { + "type": "integer", + "minimum": 1, + "description": "Number of vCPUs", + "example": 4 + } + } + }, + "Utilization": { + "type": "object", + "description": "Single-value utilization percentage (0–100). Shared by `cpu` and `memory`.", + "properties": { + "util": { + "type": "integer", + "example": 45 + } + } + }, + "PodGpuUtilization": { + "type": "object", + "description": "Per-GPU utilization metrics.", + "properties": { + "util": { + "type": "integer", + "example": 94 + }, + "memoryUtil": { + "type": "integer", + "example": 78 + } + } + }, + "PodRuntimePort": { + "type": "object", + "description": "Live port mapping for a running pod.", + "properties": { + "private": { + "type": "integer", + "example": 8888 + }, + "public": { + "type": "integer", + "nullable": true, + "example": 43210 + }, + "type": { + "type": "string", + "example": "http" + }, + "ip": { + "type": "string", + "nullable": true, + "example": "45.23.12.1" + } + } + }, + "PodRuntime": { + "type": "object", + "description": "Live utilization metrics for a running pod.", + "properties": { + "uptime": { + "type": "integer", + "description": "Seconds since the container started", + "example": 3600 + }, + "gpus": { + "type": "array", + "items": { + "$ref": "#/components/schemas/PodGpuUtilization" + } + }, + "cpu": { + "$ref": "#/components/schemas/Utilization" + }, + "memory": { + "$ref": "#/components/schemas/Utilization" + }, + "ports": { + "type": "array", + "items": { + "$ref": "#/components/schemas/PodRuntimePort" + } + } + } + }, + "PodStatus": { + "type": "string", + "description": "Lifecycle status of a pod.\n- `PROVISIONING` — pod is being allocated\n- `STARTING` — container is starting\n- `RUNNING` — container is healthy\n- `EXITED` — container exited (stopped)\n- `ERROR` — container is in an unrecoverable error state\n- `TERMINATED` — pod has been permanently deleted\n", + "enum": [ + "PROVISIONING", + "STARTING", + "RUNNING", + "EXITED", + "ERROR", + "TERMINATED" + ] + }, + "PodAction": { + "type": "string", + "description": "State transition to trigger on a pod.", + "enum": [ + "start", + "stop", + "restart", + "terminate" + ] + }, + "Cloud": { + "type": "string", + "description": "Cloud tier.\n- `SECURE` — RunPod-owned datacenter hardware\n- `COMMUNITY` — community-hosted hardware\n- `ALL` — eligible for either tier (request-only; responses always\n report the concrete tier the pod was placed on)\n", + "enum": [ + "SECURE", + "COMMUNITY", + "ALL" + ] + }, + "TemplateCategory": { + "type": "string", + "description": "Hardware family this template targets.\n- `CPU` — CPU-only workloads\n- `NVIDIA` — NVIDIA GPU workloads\n- `AMD` — AMD GPU workloads\n", + "enum": [ + "CPU", + "NVIDIA", + "AMD" + ] + }, + "Pod": { + "allOf": [ + { + "$ref": "#/components/schemas/ContainerConfig" + }, + { + "type": "object", + "required": [ + "id", + "name", + "status", + "actions", + "image", + "args", + "disk", + "mounts", + "ports", + "env", + "registry", + "gpu", + "cpu", + "cloud", + "dataCenter", + "template", + "cost", + "locked", + "tags", + "runtime", + "createdAt", + "startedAt" + ], + "properties": { + "id": { + "type": "string", + "example": "pod_abc123" + }, + "name": { + "type": "string", + "example": "my-training-pod" + }, + "status": { + "$ref": "#/components/schemas/PodStatus" + }, + "actions": { + "type": "array", + "description": "Valid state transitions for the current status.", + "items": { + "$ref": "#/components/schemas/PodAction" + } + }, + "mounts": { + "$ref": "#/components/schemas/Mounts" + }, + "gpu": { + "nullable": true, + "allOf": [ + { + "$ref": "#/components/schemas/GpuConfig" + } + ] + }, + "cpu": { + "nullable": true, + "allOf": [ + { + "$ref": "#/components/schemas/CpuConfig" + } + ] + }, + "cloud": { + "$ref": "#/components/schemas/Cloud" + }, + "dataCenter": { + "type": "string", + "nullable": true, + "description": "Data center where the pod is running (assigned by scheduler)", + "example": "US-TX-3" + }, + "template": { + "type": "string", + "nullable": true, + "description": "ID of the template this pod was created from", + "example": null + }, + "cost": { + "type": "number", + "format": "float", + "description": "Current cost in USD per hour (0.0 when EXITED or TERMINATED)", + "example": 0.35 + }, + "locked": { + "type": "boolean", + "description": "Whether the pod is locked (prevents stopping or resetting)", + "example": false + }, + "tags": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "User-defined key-value labels", + "example": { + "project": "gpt-training" + } + }, + "runtime": { + "nullable": true, + "description": "Live utilization metrics. Null when the pod is not RUNNING.", + "allOf": [ + { + "$ref": "#/components/schemas/PodRuntime" + } + ] + }, + "createdAt": { + "type": "string", + "format": "date-time", + "example": "2026-03-13T20:00:00Z" + }, + "startedAt": { + "type": "string", + "format": "date-time", + "nullable": true, + "example": "2026-03-13T20:00:00Z" + } + } + } + ] + }, + "CreatePodRequest": { + "allOf": [ + { + "$ref": "#/components/schemas/ContainerConfig" + }, + { + "type": "object", + "required": [ + "name", + "image" + ], + "description": "Request body for creating a pod. Exactly one of `gpu` or `cpu`\nmust be set — enforced at the handler layer. CPU pod creation is\nstubbed pending AE-2991 and returns `501 Not Implemented`.\n", + "properties": { + "name": { + "type": "string", + "minLength": 1, + "example": "my-training-pod" + }, + "mounts": { + "$ref": "#/components/schemas/Mounts" + }, + "gpu": { + "$ref": "#/components/schemas/GpuConfig" + }, + "cpu": { + "$ref": "#/components/schemas/CpuConfig" + }, + "cloud": { + "$ref": "#/components/schemas/Cloud" + }, + "dataCenter": { + "type": "string", + "description": "Preferred data center for placement. The upstream scheduler\naccepts a single data center; pass null/omit to let the\nscheduler choose.\n", + "nullable": true, + "example": "US-TX-3" + } + } + } + ] + }, + "UpdatePodRequest": { + "allOf": [ + { + "$ref": "#/components/schemas/ContainerConfig" + }, + { + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 1 + }, + "mounts": { + "$ref": "#/components/schemas/Mounts" + }, + "locked": { + "type": "boolean", + "description": "Lock the pod (true) or unlock it (false). Locked pods cannot be stopped or reset." + } + } + } + ] + }, + "PodActionRequest": { + "type": "object", + "required": [ + "action" + ], + "properties": { + "action": { + "$ref": "#/components/schemas/PodAction" + } + } + }, + "ListPodsResponse": { + "type": "object", + "required": [ + "pods" + ], + "properties": { + "pods": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Pod" + } + } + } + }, + "Template": { + "allOf": [ + { + "$ref": "#/components/schemas/ContainerConfig" + }, + { + "type": "object", + "required": [ + "id", + "name", + "image", + "args", + "disk", + "mounts", + "ports", + "env", + "registry", + "serverless", + "public", + "category" + ], + "properties": { + "id": { + "type": "string", + "example": "tpl_abc" + }, + "name": { + "type": "string", + "example": "My PyTorch Template" + }, + "mounts": { + "$ref": "#/components/schemas/TemplateMounts" + }, + "serverless": { + "type": "boolean", + "description": "Whether this template is for serverless workers (true) or pods (false)", + "example": false + }, + "public": { + "type": "boolean", + "description": "Whether this template is visible to other RunPod users", + "example": false + }, + "category": { + "$ref": "#/components/schemas/TemplateCategory" + } + } + } + ] + }, + "CreateTemplateRequest": { + "allOf": [ + { + "$ref": "#/components/schemas/ContainerConfig" + }, + { + "type": "object", + "required": [ + "name", + "image", + "category" + ], + "properties": { + "name": { + "type": "string", + "minLength": 1, + "example": "My PyTorch Template" + }, + "mounts": { + "$ref": "#/components/schemas/TemplateMounts" + }, + "serverless": { + "type": "boolean", + "default": false + }, + "public": { + "type": "boolean", + "default": false + }, + "category": { + "$ref": "#/components/schemas/TemplateCategory" + } + } + } + ] + }, + "UpdateTemplateRequest": { + "allOf": [ + { + "$ref": "#/components/schemas/ContainerConfig" + }, + { + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 1 + }, + "mounts": { + "$ref": "#/components/schemas/TemplateMounts" + }, + "serverless": { + "type": "boolean" + }, + "public": { + "type": "boolean" + }, + "category": { + "$ref": "#/components/schemas/TemplateCategory" + } + } + } + ] + }, + "ListTemplatesResponse": { + "type": "object", + "required": [ + "templates" + ], + "properties": { + "templates": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Template" + } + } + } + }, + "Tag": { + "type": "object", + "required": [ + "id", + "key", + "value" + ], + "additionalProperties": false, + "properties": { + "id": { + "type": "string", + "description": "Tag identifier", + "example": "tag_abc123" + }, + "key": { + "type": "string", + "minLength": 1, + "description": "Tag key", + "example": "project" + }, + "value": { + "type": "string", + "minLength": 1, + "description": "Tag value", + "example": "gpt-training" + } + } + }, + "CreateTagRequest": { + "type": "object", + "required": [ + "key", + "value" + ], + "additionalProperties": false, + "properties": { + "key": { + "type": "string", + "minLength": 1, + "example": "project" + }, + "value": { + "type": "string", + "minLength": 1, + "example": "gpt-training" + } + } + }, + "UpdateTagRequest": { + "type": "object", + "minProperties": 1, + "additionalProperties": false, + "description": "At least one of `key` or `value` must be provided.", + "properties": { + "key": { + "type": "string", + "minLength": 1, + "example": "project" + }, + "value": { + "type": "string", + "minLength": 1, + "example": "gpt-training" + } + } + }, + "ListTagsResponse": { + "type": "object", + "required": [ + "tags" + ], + "additionalProperties": false, + "properties": { + "tags": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Tag" + } + } + } + }, + "NetworkVolume": { + "type": "object", + "required": [ + "id", + "name", + "size", + "dataCenter" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique network volume identifier", + "example": "agv6w2qcg7" + }, + "name": { + "type": "string", + "description": "Human-readable name (not required to be unique)", + "example": "my-dataset" + }, + "size": { + "type": "integer", + "minimum": 1, + "maximum": 4000, + "description": "Allocated storage in GB", + "example": 50 + }, + "dataCenter": { + "type": "string", + "description": "Data center location; immutable after creation", + "example": "EU-RO-1" + } + } + }, + "CreateNetworkVolumeRequest": { + "type": "object", + "required": [ + "name", + "size", + "dataCenter" + ], + "properties": { + "name": { + "type": "string", + "minLength": 1, + "description": "Human-readable name", + "example": "my-dataset" + }, + "size": { + "type": "integer", + "minimum": 1, + "maximum": 4000, + "description": "Storage to allocate in GB", + "example": 50 + }, + "dataCenter": { + "type": "string", + "minLength": 1, + "description": "Data center in which to create the volume", + "example": "EU-RO-1" + } + } + }, + "UpdateNetworkVolumeRequest": { + "type": "object", + "description": "All fields are optional. Only provided fields are updated.", + "properties": { + "name": { + "type": "string", + "minLength": 1, + "description": "New human-readable name", + "example": "renamed-volume" + }, + "size": { + "type": "integer", + "minimum": 1, + "maximum": 4000, + "description": "New size in GB. Must be greater than or equal to the current size —\nnetwork volume storage cannot be reduced.\n", + "example": 100 + } + } + }, + "ListNetworkVolumesResponse": { + "type": "object", + "required": [ + "networkVolumes" + ], + "properties": { + "networkVolumes": { + "type": "array", + "items": { + "$ref": "#/components/schemas/NetworkVolume" + } + } + } + }, + "Registry": { + "type": "object", + "required": [ + "id", + "name" + ], + "properties": { + "id": { + "type": "string", + "example": "reg_abc" + }, + "name": { + "type": "string", + "example": "my-private-registry" + } + } + }, + "CreateRegistryRequest": { + "type": "object", + "required": [ + "name", + "username", + "password" + ], + "properties": { + "name": { + "type": "string", + "minLength": 1, + "example": "my-private-registry" + }, + "username": { + "type": "string", + "minLength": 1, + "description": "Registry username (write-only, not returned in responses)" + }, + "password": { + "type": "string", + "minLength": 1, + "description": "Registry password (write-only, not returned in responses)" + } + } + }, + "ListRegistriesResponse": { + "type": "object", + "required": [ + "registries" + ], + "properties": { + "registries": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Registry" + } + } + } + }, + "Repository": { + "type": "object", + "description": "A project namespace that holds one or more images.", + "properties": { + "name": { + "type": "string", + "description": "Repository name (lowercase, [a-z0-9_-]).", + "example": "my-app" + }, + "created_at": { + "type": "string", + "format": "date-time" + } + } + }, + "CreateRepositoryRequest": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "Repository name; must be unique within your account.", + "example": "my-app" + } + } + }, + "ListRepositoriesResponse": { + "type": "object", + "required": [ + "repositories" + ], + "properties": { + "repositories": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Repository" + } + } + } + }, + "Image": { + "type": "object", + "description": "A named container image within a repository. Builds push versions of this image as `/:v`.", + "properties": { + "name": { + "type": "string", + "description": "Image name (lowercase, [a-z0-9_-]).", + "example": "api" + }, + "next_version": { + "type": "integer", + "description": "The version that will be assigned to the next build of this image.", + "example": 3 + }, + "created_at": { + "type": "string", + "format": "date-time" + }, + "versions": { + "type": "array", + "description": "Pullable image URLs for every successful build of this image, ordered oldest to newest. Empty until the first build succeeds.", + "items": { + "type": "string" + }, + "example": [ + "registry.example.com/user-abc/my-app/api:v1", + "registry.example.com/user-abc/my-app/api:v2" + ] + } + } + }, + "CreateImageRequest": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "Image name; must be unique within the repository.", + "example": "api" + } + } + }, + "ListImagesResponse": { + "type": "object", + "required": [ + "images" + ], + "properties": { + "images": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Image" + } + } + } + }, + "Build": { + "type": "object", + "description": "A single build job for a specific image.", + "properties": { + "id": { + "type": "string", + "example": "build_01HWZ4..." + }, + "version": { + "type": "integer", + "description": "Auto-assigned monotonic version for this image. The build is always pushed to `/:v`.", + "example": 3 + }, + "status": { + "type": "string", + "enum": [ + "queued", + "running", + "succeeded", + "failed", + "cancelled" + ], + "example": "queued" + }, + "image": { + "type": "string", + "description": "Fully-qualified pullable image URL. Use this directly with `docker pull`.", + "example": "registry.example.com/user-abc/my-app/api:v3" + }, + "result_digest": { + "type": "string", + "nullable": true, + "description": "Image digest, set when status is `succeeded`.", + "example": "sha256:abc..." + }, + "failure_reason": { + "type": "string", + "nullable": true + }, + "source": { + "description": "The source spec the build was submitted with. Same shape as `CreateBuildRequest.source`.", + "oneOf": [ + { + "$ref": "#/components/schemas/GitSource" + }, + { + "$ref": "#/components/schemas/InlineSource" + } + ], + "discriminator": { + "propertyName": "type", + "mapping": { + "git": "#/components/schemas/GitSource", + "inline": "#/components/schemas/InlineSource" + } + } + }, + "dockerfile_path": { + "type": "string" + }, + "build_args": { + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "target_stage": { + "type": "string", + "nullable": true + }, + "queued_at": { + "type": "string", + "format": "date-time" + }, + "started_at": { + "type": "string", + "format": "date-time", + "nullable": true + }, + "finished_at": { + "type": "string", + "format": "date-time", + "nullable": true + } + } + }, + "GitSource": { + "type": "object", + "description": "Build context cloned from a git URL.", + "required": [ + "type", + "url" + ], + "properties": { + "type": { + "type": "string", + "enum": [ + "git" + ] + }, + "url": { + "type": "string", + "description": "HTTPS git URL.", + "example": "https://github.com/user/repo" + }, + "ref": { + "type": "string", + "description": "Branch, tag, or commit. Defaults to the repository's default branch.", + "example": "main" + } + } + }, + "InlineSource": { + "type": "object", + "description": "Build context defined inline — a Dockerfile body, no surrounding files.", + "required": [ + "type", + "dockerfile_content" + ], + "properties": { + "type": { + "type": "string", + "enum": [ + "inline" + ] + }, + "dockerfile_content": { + "type": "string", + "description": "Dockerfile contents to build.", + "example": "FROM alpine:3.20\nCMD [\"echo\", \"hello\"]\n" + } + } + }, + "CreateBuildRequest": { + "type": "object", + "required": [ + "source" + ], + "properties": { + "source": { + "description": "Where the build context comes from.", + "oneOf": [ + { + "$ref": "#/components/schemas/GitSource" + }, + { + "$ref": "#/components/schemas/InlineSource" + } + ], + "discriminator": { + "propertyName": "type", + "mapping": { + "git": "#/components/schemas/GitSource", + "inline": "#/components/schemas/InlineSource" + } + } + }, + "dockerfile_path": { + "type": "string", + "description": "Path to the Dockerfile within the source. Defaults to `Dockerfile` at the source root.", + "example": "Dockerfile" + }, + "build_args": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "Docker `--build-arg` values." + }, + "target_stage": { + "type": "string", + "nullable": true, + "description": "For multi-stage Dockerfiles, the stage to build (Docker `--target`). Omit to build the final stage." + } + } + }, + "ListBuildsResponse": { + "type": "object", + "required": [ + "builds" + ], + "properties": { + "builds": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Build" + } + } + } + }, + "GpuType": { + "type": "object", + "required": [ + "id", + "name", + "pool", + "manufacturer", + "memory", + "secure", + "community", + "price", + "maxCount" + ], + "properties": { + "id": { + "type": "string", + "description": "Individual GPU type identifier (use for pod creation)", + "example": "NVIDIA GeForce RTX 4090" + }, + "name": { + "type": "string", + "example": "RTX 4090" + }, + "pool": { + "type": "string", + "nullable": true, + "description": "Serverless GPU pool ID (use for endpoint creation). Null if GPU is not in a serverless pool.", + "example": "ADA_24" + }, + "manufacturer": { + "type": "string", + "example": "NVIDIA" + }, + "memory": { + "type": "integer", + "description": "VRAM in GB", + "example": 24 + }, + "secure": { + "type": "boolean", + "description": "Available on secure cloud", + "example": true + }, + "community": { + "type": "boolean", + "description": "Available on community cloud", + "example": true + }, + "price": { + "type": "object", + "required": [ + "secure", + "community" + ], + "properties": { + "secure": { + "type": "number", + "format": "float", + "example": 0.44 + }, + "community": { + "type": "number", + "format": "float", + "example": 0.31 + } + } + }, + "maxCount": { + "type": "object", + "required": [ + "secure", + "community" + ], + "properties": { + "secure": { + "type": "integer", + "example": 8 + }, + "community": { + "type": "integer", + "example": 4 + } + } + }, + "availability": { + "description": "Overall GPU availability. Present only when requested with include=availability.", + "$ref": "#/components/schemas/AvailabilityLevel" + }, + "dataCenters": { + "type": "array", + "description": "Per-datacenter GPU availability. Present only when requested with include=availability.", + "items": { + "$ref": "#/components/schemas/DataCenterAvailability" + } + } + } + }, + "AvailabilityLevel": { + "type": "string", + "description": "Catalog stock availability level.", + "enum": [ + "NONE", + "LOW", + "MEDIUM", + "HIGH" + ] + }, + "CatalogResourceAvailability": { + "type": "object", + "required": [ + "id", + "name", + "availability" + ], + "properties": { + "id": { + "type": "string", + "description": "Catalog resource identifier.", + "example": "NVIDIA GeForce RTX 4090" + }, + "name": { + "type": "string", + "description": "Human-readable catalog resource name.", + "example": "RTX 4090" + }, + "availability": { + "$ref": "#/components/schemas/AvailabilityLevel" + } + } + }, + "DataCenterAvailability": { + "type": "object", + "required": [ + "id", + "name", + "availability" + ], + "properties": { + "id": { + "type": "string", + "description": "Data center identifier.", + "example": "US-CA-2" + }, + "name": { + "type": "string", + "description": "Human-readable data center name.", + "example": "US California 2" + }, + "availability": { + "$ref": "#/components/schemas/AvailabilityLevel" + } + } + }, + "ListGpuTypesResponse": { + "type": "object", + "required": [ + "gpus" + ], + "properties": { + "gpus": { + "type": "array", + "items": { + "$ref": "#/components/schemas/GpuType" + } + } + } + }, + "CpuType": { + "type": "object", + "required": [ + "id", + "name", + "group", + "vcpu", + "ramGbPerVcpu" + ], + "properties": { + "id": { + "type": "string", + "description": "CPU flavor identifier (use in cpu.id for pod creation)", + "example": "cpu5c" + }, + "name": { + "type": "string", + "description": "Human-readable flavor name", + "example": "Compute-Optimized" + }, + "group": { + "type": "string", + "description": "CPU generation group", + "example": "Gen 5" + }, + "vcpu": { + "type": "object", + "required": [ + "min", + "max" + ], + "properties": { + "min": { + "type": "integer", + "example": 2 + }, + "max": { + "type": "integer", + "example": 32 + } + } + }, + "ramGbPerVcpu": { + "type": "number", + "format": "float", + "description": "GB of RAM allocated per vCPU. Multiply by the chosen vCPU\ncount (within `vcpu.min`..`vcpu.max`) to get the total RAM\nfor an instance of this flavor. May be fractional.\n", + "example": 2.5 + } + } + }, + "ListCpuTypesResponse": { + "type": "object", + "required": [ + "cpus" + ], + "properties": { + "cpus": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CpuType" + } + } + } + }, + "DataCenter": { + "type": "object", + "required": [ + "id", + "name", + "region", + "volumes", + "compliance" + ], + "properties": { + "id": { + "type": "string", + "example": "US-TX-3" + }, + "name": { + "type": "string", + "example": "US Texas 3" + }, + "region": { + "$ref": "#/components/schemas/DataCenterRegion" + }, + "volumes": { + "type": "boolean", + "description": "Whether this data center supports network volumes", + "example": true + }, + "compliance": { + "type": "array", + "description": "Compliance certifications held by this data center", + "items": { + "$ref": "#/components/schemas/Compliance" + }, + "example": [ + "GDPR", + "ISO_IEC_27001", + "SOC_2_TYPE_2" + ] + }, + "gpuAvailability": { + "type": "array", + "description": "Per-GPU availability in this data center. Present only when requested with include=gpuAvailability.", + "items": { + "$ref": "#/components/schemas/CatalogResourceAvailability" + } + } + } + }, + "DataCenterRegion": { + "type": "string", + "description": "Continental region containing the data center.", + "example": "EUROPE", + "enum": [ + "NORTH_AMERICA", + "SOUTH_AMERICA", + "EUROPE", + "ASIA", + "MIDDLE_EAST", + "AFRICA", + "OCEANIA", + "ANTARCTICA", + "UNKNOWN" + ] + }, + "Compliance": { + "type": "string", + "description": "Compliance certifications.", + "enum": [ + "GDPR", + "ISO_IEC_27001", + "ISO_14001", + "PCI_DSS", + "HITRUST", + "SOC_1_TYPE_2", + "SOC_2_TYPE_2", + "SOC_3_TYPE_2", + "ITAR", + "FISMA_HIGH", + "HIPAA", + "RENEWABLE" + ] + }, + "ListDataCentersResponse": { + "type": "object", + "required": [ + "dataCenters" + ], + "properties": { + "dataCenters": { + "type": "array", + "items": { + "$ref": "#/components/schemas/DataCenter" + } + } + } + }, + "ErrorResponse": { + "type": "object", + "properties": { + "title": { + "type": "string", + "description": "Short human-readable summary", + "example": "Not Found" + }, + "status": { + "type": "integer", + "description": "HTTP status code", + "example": 404 + }, + "detail": { + "type": "string", + "description": "Human-readable explanation", + "example": "pod not found" + } + } + }, + "ValidatationErrorResponse": { + "type": "object", + "properties": { + "title": { + "type": "string", + "description": "Short human-readable summary", + "example": "Unprocessable Entity" + }, + "status": { + "type": "integer", + "description": "HTTP status code", + "example": 422 + }, + "errors": { + "type": "array", + "items": { + "type": "string", + "example": "$: minProperties: got 0, want 1" + }, + "description": "Human-readable explanation" + } + } + } + } + }, + "paths": { + "/v2/pods": { + "get": { + "operationId": "listPods", + "summary": "List pods", + "description": "Returns all pods owned by the authenticated user.", + "tags": [ + "Pods" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListPodsResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + }, + "post": { + "operationId": "createPod", + "summary": "Create a pod", + "description": "Creates a new pod. Specify `gpu` for compute.\nContainerConfig fields can be spread from a template response.\n", + "tags": [ + "Pods" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreatePodRequest" + } + } + } + }, + "responses": { + "201": { + "description": "Created", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Pod" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/pods/{id}": { + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "Pod identifier", + "example": "pod_abc123" + } + ], + "get": { + "operationId": "getPod", + "summary": "Get a pod", + "description": "Returns a single pod by ID.", + "tags": [ + "Pods" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Pod" + } + } + } + }, + "404": { + "description": "Pod not found", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + }, + "patch": { + "operationId": "updatePod", + "summary": "Update a pod", + "description": "Updates pod configuration. Only provided fields are changed.", + "tags": [ + "Pods" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdatePodRequest" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Pod" + } + } + } + }, + "404": { + "description": "Pod not found", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + }, + "delete": { + "operationId": "deletePod", + "summary": "Terminate a pod", + "description": "Permanently terminates and deletes a pod.", + "tags": [ + "Pods" + ], + "responses": { + "204": { + "description": "Terminated" + }, + "404": { + "description": "Pod not found", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/pods/{id}/action": { + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "example": "pod_abc123" + } + ], + "post": { + "operationId": "podAction", + "summary": "Trigger a pod state transition", + "description": "Triggers a state transition on a pod. Valid actions depend on the current status\nand are listed in the pod's `actions` field.\n", + "tags": [ + "Pods" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PodActionRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Action applied — returns updated pod", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Pod" + } + } + } + }, + "204": { + "description": "Pod terminated (for action=terminate)" + }, + "404": { + "description": "Pod not found", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Action not valid for current pod status", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/templates": { + "get": { + "operationId": "listTemplates", + "summary": "List templates", + "description": "Returns all templates owned by the authenticated user.", + "tags": [ + "Templates" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListTemplatesResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + }, + "post": { + "operationId": "createTemplate", + "summary": "Create a template", + "tags": [ + "Templates" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateTemplateRequest" + } + } + } + }, + "responses": { + "201": { + "description": "Created", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Template" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/templates/{id}": { + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "example": "tpl_abc" + } + ], + "get": { + "operationId": "getTemplate", + "summary": "Get a template", + "tags": [ + "Templates" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Template" + } + } + } + }, + "404": { + "description": "Template not found", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + }, + "patch": { + "operationId": "updateTemplate", + "summary": "Update a template", + "description": "Updates template configuration. Only provided fields are changed.", + "tags": [ + "Templates" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateTemplateRequest" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Template" + } + } + } + }, + "404": { + "description": "Template not found", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + }, + "delete": { + "operationId": "deleteTemplate", + "summary": "Delete a template", + "tags": [ + "Templates" + ], + "responses": { + "204": { + "description": "Deleted" + }, + "404": { + "description": "Template not found", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/tags": { + "get": { + "operationId": "listTags", + "summary": "List tags", + "description": "Returns all tags owned by the authenticated user.", + "tags": [ + "Tags" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListTagsResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + }, + "post": { + "operationId": "createTag", + "summary": "Create a tag", + "description": "Creates a user-defined key-value tag.", + "tags": [ + "Tags" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateTagRequest" + } + } + } + }, + "responses": { + "201": { + "description": "Created", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Tag" + } + } + } + }, + "400": { + "description": "Invalid request body", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/tags/{id}": { + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "Tag identifier", + "example": "tag_abc123" + } + ], + "get": { + "operationId": "getTag", + "summary": "Get a tag", + "description": "Returns a single tag by ID.", + "tags": [ + "Tags" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Tag" + } + } + } + }, + "404": { + "description": "Tag not found", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + }, + "patch": { + "operationId": "updateTag", + "summary": "Update a tag", + "description": "Updates a tag. At least one of `key` or `value` must be provided.", + "tags": [ + "Tags" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateTagRequest" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Tag" + } + } + } + }, + "404": { + "description": "Tag not found", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "422": { + "description": "Unprocessable request body (missing `key` and/or `value`)", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + }, + "delete": { + "operationId": "deleteTag", + "summary": "Delete a tag", + "description": "Deletes a tag.", + "tags": [ + "Tags" + ], + "responses": { + "204": { + "description": "Deleted" + }, + "404": { + "description": "Tag not found", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/network-volumes": { + "get": { + "operationId": "listNetworkVolumes", + "summary": "List network volumes", + "description": "Returns all network volumes owned by the authenticated user.", + "tags": [ + "Network Volumes" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListNetworkVolumesResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + }, + "post": { + "operationId": "createNetworkVolume", + "summary": "Create a network volume", + "description": "Provisions a new network volume in the specified data center.", + "tags": [ + "Network Volumes" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateNetworkVolumeRequest" + } + } + } + }, + "responses": { + "201": { + "description": "Created", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NetworkVolume" + } + } + } + }, + "400": { + "description": "Invalid request body", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/network-volumes/{id}": { + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "Network volume identifier", + "example": "agv6w2qcg7" + } + ], + "get": { + "operationId": "getNetworkVolume", + "summary": "Get a network volume", + "description": "Returns a single network volume by ID.", + "tags": [ + "Network Volumes" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NetworkVolume" + } + } + } + }, + "404": { + "description": "Network volume not found", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + }, + "patch": { + "operationId": "updateNetworkVolume", + "summary": "Update a network volume", + "description": "Updates mutable fields on a network volume. Only provided fields are changed.\nNote: `size` may only increase; attempts to reduce size will be rejected.\n", + "tags": [ + "Network Volumes" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateNetworkVolumeRequest" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NetworkVolume" + } + } + } + }, + "400": { + "description": "Invalid request body or size decrease attempted", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "404": { + "description": "Network volume not found", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + }, + "delete": { + "operationId": "deleteNetworkVolume", + "summary": "Delete a network volume", + "description": "Permanently deletes a network volume and releases its storage.", + "tags": [ + "Network Volumes" + ], + "responses": { + "204": { + "description": "Deleted" + }, + "404": { + "description": "Network volume not found", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/registries": { + "get": { + "operationId": "listRegistries", + "summary": "List container registries", + "description": "Returns all container registry credentials owned by the authenticated user.", + "tags": [ + "Registries" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListRegistriesResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + }, + "post": { + "operationId": "createRegistry", + "summary": "Create a container registry credential", + "description": "Stores credentials for a private container registry. Credentials are write-only.", + "tags": [ + "Registries" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateRegistryRequest" + } + } + } + }, + "responses": { + "201": { + "description": "Created", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Registry" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/registries/{id}": { + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "example": "reg_abc" + } + ], + "get": { + "operationId": "getRegistry", + "summary": "Get a container registry credential", + "tags": [ + "Registries" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Registry" + } + } + } + }, + "404": { + "description": "Registry not found", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + }, + "delete": { + "operationId": "deleteRegistry", + "summary": "Delete a container registry credential", + "tags": [ + "Registries" + ], + "responses": { + "204": { + "description": "Deleted" + }, + "404": { + "description": "Registry not found", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/catalog/gpus": { + "get": { + "operationId": "listGpuTypes", + "summary": "List GPU types", + "description": "Returns available GPU types with pricing. Availability is included only when requested with include=availability.", + "tags": [ + "Catalog" + ], + "parameters": [ + { + "name": "include", + "in": "query", + "required": false, + "description": "Comma-separated optional expansions. Supported value: availability.", + "schema": { + "type": "string", + "example": "availability" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListGpuTypesResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/catalog/gpus/{id}": { + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "example": "NVIDIA GeForce RTX 4090" + } + ], + "get": { + "operationId": "getGpuType", + "summary": "Get a GPU type", + "description": "Returns a single GPU type with pricing. Availability details are included only when requested with include=availability.", + "tags": [ + "Catalog" + ], + "parameters": [ + { + "name": "include", + "in": "query", + "required": false, + "description": "Comma-separated optional expansions. Supported value: availability.", + "schema": { + "type": "string", + "example": "availability" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GpuType" + } + } + } + }, + "404": { + "description": "GPU type not found", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/catalog/cpus": { + "get": { + "operationId": "listCpuTypes", + "summary": "List CPU types", + "description": "Returns available CPU flavors.", + "tags": [ + "Catalog" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListCpuTypesResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/catalog/datacenters": { + "get": { + "operationId": "listDataCenters", + "summary": "List data centers", + "description": "Returns available data center locations.", + "tags": [ + "Catalog" + ], + "parameters": [ + { + "name": "include", + "in": "query", + "required": false, + "description": "Comma-separated optional expansions. Supported value: gpuAvailability.", + "schema": { + "type": "string", + "example": "gpuAvailability" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListDataCentersResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/repositories": { + "get": { + "operationId": "listRepositories", + "summary": "List repositories", + "tags": [ + "Builds" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListRepositoriesResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + }, + "post": { + "operationId": "createRepository", + "summary": "Create a repository", + "tags": [ + "Builds" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateRepositoryRequest" + } + } + } + }, + "responses": { + "201": { + "description": "Created", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Repository" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/repositories/{repo_name}": { + "parameters": [ + { + "name": "repo_name", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "delete": { + "operationId": "deleteRepository", + "summary": "Delete a repository", + "description": "Without `?purge=true`, the repository must be empty (no images) or the response is 409 with `code=repository_not_empty`. With `?purge=true`, cascades through all images and builds under the repository; any active builds are cancelled in the same transaction before deletion.\n", + "tags": [ + "Builds" + ], + "parameters": [ + { + "name": "purge", + "in": "query", + "required": false, + "schema": { + "type": "boolean", + "default": false + }, + "description": "When true, cascade-deletes images and builds (cancelling any active builds) instead of refusing on non-empty.\n" + } + ], + "responses": { + "204": { + "description": "Deleted" + }, + "404": { + "description": "Repository not found (or owned by another user)", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Repository has images and purge was not set", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/repositories/{repo_name}/images": { + "parameters": [ + { + "name": "repo_name", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "get": { + "operationId": "listImages", + "summary": "List images in a repository", + "tags": [ + "Builds" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListImagesResponse" + } + } + } + }, + "404": { + "description": "Repository not found", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + }, + "post": { + "operationId": "createImage", + "summary": "Create an image in a repository", + "tags": [ + "Builds" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateImageRequest" + } + } + } + }, + "responses": { + "201": { + "description": "Created", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Image" + } + } + } + }, + "404": { + "description": "Repository not found", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/repositories/{repo_name}/images/{image_name}": { + "parameters": [ + { + "name": "repo_name", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "image_name", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "get": { + "operationId": "getImage", + "summary": "Get an image", + "tags": [ + "Builds" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Image" + } + } + } + }, + "404": { + "description": "Image not found", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + }, + "delete": { + "operationId": "deleteImage", + "summary": "Delete an image", + "description": "Without `?purge=true`, the image must have no builds or the response is 409 with `code=image_not_empty`. With `?purge=true`, cascade-deletes all builds (cancelling any that are active).\n", + "tags": [ + "Builds" + ], + "parameters": [ + { + "name": "purge", + "in": "query", + "required": false, + "schema": { + "type": "boolean", + "default": false + } + } + ], + "responses": { + "204": { + "description": "Deleted" + }, + "404": { + "description": "Image not found (or owned by another user)", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Image has builds and purge was not set", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/repositories/{repo_name}/images/{image_name}/builds": { + "parameters": [ + { + "name": "repo_name", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "image_name", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "get": { + "operationId": "listBuilds", + "summary": "List builds for an image", + "tags": [ + "Builds" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListBuildsResponse" + } + } + } + }, + "404": { + "description": "Image not found", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + }, + "post": { + "operationId": "createBuild", + "summary": "Submit a build for an image", + "description": "Queues a build. The build runs asynchronously; poll `GET /v2/builds/{id}` (or list builds for this image) until status is `succeeded` or `failed`. Pass `Idempotency-Key` to safely retry network failures.\n", + "tags": [ + "Builds" + ], + "parameters": [ + { + "in": "header", + "name": "Idempotency-Key", + "required": false, + "schema": { + "type": "string" + }, + "description": "Client-supplied key. Repeating with the same key returns the existing build." + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateBuildRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Existing build returned (idempotency-key match)", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Build" + } + } + } + }, + "201": { + "description": "Build created", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Build" + } + } + } + }, + "404": { + "description": "Image not found", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/builds/{id}": { + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "example": "build_abc" + } + ], + "get": { + "operationId": "getBuild", + "summary": "Get a build by id", + "tags": [ + "Builds" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Build" + } + } + } + }, + "404": { + "description": "Build not found", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + }, + "delete": { + "operationId": "deleteBuild", + "summary": "Delete (and cancel, if active) a build", + "description": "Deletes the build resource. If the build is currently in an active state (queued or running), it is transitioned to `cancelled` in the same transaction before removal — the builder learns from a status poll and aborts buildctl.\n", + "tags": [ + "Builds" + ], + "responses": { + "204": { + "description": "Deleted" + }, + "404": { + "description": "Build not found (or owned by another user)", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/builds/{id}/cancel": { + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "example": "build_abc" + } + ], + "post": { + "operationId": "cancelBuild", + "summary": "Cancel a build", + "description": "Cancels a queued or running build. Idempotent — cancelling an already-cancelled build returns it unchanged. Returns 409 if the build already reached a terminal state (`success` or `failed`). The running build execution is stopped asynchronously by the scheduler; the build transitions to `cancelled` immediately.\n", + "tags": [ + "Builds" + ], + "responses": { + "200": { + "description": "Build cancelled (or already cancelled)", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Build" + } + } + } + }, + "404": { + "description": "Build not found (or owned by another user)", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Build already reached a terminal state", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/builds/{id}/logs": { + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "example": "build_abc" + } + ], + "get": { + "operationId": "getBuildLogs", + "summary": "Fetch the build log", + "description": "Returns the captured stdout+stderr of the build. By default (`follow=false`), responds with a `text/plain` snapshot of whatever has been captured so far and closes the connection — poll to see content grow while a build is running.\n\nWith `?follow=true`, the response is a Server-Sent Events stream: the server holds the connection open and pushes `data:` events as new content arrives, then emits a final `event: end` and closes when the build terminates.\n", + "tags": [ + "Builds" + ], + "parameters": [ + { + "name": "follow", + "in": "query", + "required": false, + "schema": { + "type": "boolean", + "default": false + }, + "description": "When true, stream new log content as Server-Sent Events instead of returning a snapshot." + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "text/plain": { + "schema": { + "type": "string", + "description": "Snapshot of the current build log. Returned when `follow=false` or the param is absent." + } + }, + "text/event-stream": { + "schema": { + "type": "string", + "description": "SSE stream. Each new chunk of log content is emitted as one or more\n`data: ` events (one per log line; lines reassemble by joining with `\\n`).\nWhen the build reaches a terminal state, the server emits `event: end\\ndata: \\n\\n` and closes.\n" + } + } + } + }, + "404": { + "description": "Build not found", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + } + } +} \ No newline at end of file From 3fdf94a7896a1e84adf080582fd507b6392ac395 Mon Sep 17 00:00:00 2001 From: lgunreddi Date: Thu, 25 Jun 2026 14:43:10 -0400 Subject: [PATCH 04/41] Update docs.json --- docs.json | 33 +++++++++++++++++++++++++++++++-- 1 file changed, 31 insertions(+), 2 deletions(-) diff --git a/docs.json b/docs.json index 5f09df05..ee973039 100644 --- a/docs.json +++ b/docs.json @@ -519,9 +519,38 @@ "pages": [ "api-reference-v2/overview" ] - } + }, + { + "group": "Pods", + "openapi": "api-reference-v2/openapi.json", + "pages": [ + "GET /v2/pods", + "POST /v2/pods", + "GET /v2/pods/{id}", + "PATCH /v2/pods/{id}", + "DELETE /v2/pods/{id}", + "POST /v2/pods/{id}/action" ] - }, + }, + { + "group": "Templates", + "openapi": "api-reference-v2/openapi.json", + "pages": [ + "GET /v2/templates", + "POST /v2/templates", + "GET /v2/templates/{id}" + ] + }, + { + "group": "Network Volumes", + "openapi": "api-reference-v2/openapi.json", + "pages": [ + "GET /v2/network-volumes", + "POST /v2/network-volumes" + ] + } + ] + }, { "tab": "Models", "groups": [ From d701ca7134176044f1ed5897fda2c5c78a9d193d Mon Sep 17 00:00:00 2001 From: lgunreddi Date: Thu, 25 Jun 2026 14:57:21 -0400 Subject: [PATCH 05/41] Delete api-reference-v2/openapi.json --- api-reference-v2/openapi.json | 3529 --------------------------------- 1 file changed, 3529 deletions(-) delete mode 100644 api-reference-v2/openapi.json diff --git a/api-reference-v2/openapi.json b/api-reference-v2/openapi.json deleted file mode 100644 index 2b03fb0f..00000000 --- a/api-reference-v2/openapi.json +++ /dev/null @@ -1,3529 +0,0 @@ -{ - "openapi": "3.0.3", - "info": { - "title": "RunPod REST API", - "version": "2.0.0", - "description": "RunPod public REST API — v2" - }, - "servers": [ - { - "url": "/", - "description": "Current server" - } - ], - "security": [ - { - "bearerAuth": [] - } - ], - "components": { - "securitySchemes": { - "bearerAuth": { - "type": "http", - "scheme": "bearer", - "bearerFormat": "RunPod API Key" - } - }, - "schemas": { - "ContainerConfig": { - "type": "object", - "description": "Reusable container configuration shared across templates, pods, and endpoints. Adding a field here automatically propagates to all three resources.\n", - "properties": { - "image": { - "type": "string", - "description": "Docker image reference", - "example": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1" - }, - "args": { - "type": "string", - "description": "Arguments passed to the container entrypoint", - "example": "" - }, - "disk": { - "type": "integer", - "minimum": 1, - "description": "Container disk in GB (ephemeral, wiped on restart)", - "example": 50 - }, - "ports": { - "type": "array", - "description": "Exposed ports, formatted as port/protocol", - "items": { - "type": "string" - }, - "example": [ - "8888/http", - "22/tcp" - ] - }, - "env": { - "type": "object", - "additionalProperties": { - "type": "string" - }, - "description": "Environment variables as key-value pairs", - "example": { - "JUPYTER_PASSWORD": "hunter2" - } - }, - "registry": { - "type": "string", - "nullable": true, - "description": "Container registry credential ID (for private images)", - "example": null - } - } - }, - "Mounts": { - "type": "object", - "additionalProperties": false, - "description": "Storage mounts attached to a pod. At-most-one of `persistent` or\n`network` may be set today (mutually exclusive, enforced at the\nhandler with 400 if both are present). The `network` field is an\narray for forward compatibility with eventual multi-network-volume\nsupport, but `maxItems` is 1 today.\n\nPATCH semantics:\n- Omitting `mounts` or sending `{}` leaves the existing mount\n unchanged.\n- An explicit `network: []` is rejected with 400 (clearing mounts\n is not supported).\n- Mount kind is fixed at create — a PATCH that introduces a kind\n not present at create (persistent on a network pod, network on\n a persistent pod, or any mount on a previously-mountless pod)\n is rejected with 400.\n- The `volumeId` of a network mount is immutable; a PATCH that\n names a different `volumeId` is rejected with 400.\n- Partial mounts are not supported — every mount entry must\n include the full schema (`size` + `path` for persistent,\n `volumeId` + `path` for network). Missing required fields → 422.\n", - "properties": { - "persistent": { - "$ref": "#/components/schemas/PersistentMount" - }, - "network": { - "type": "array", - "maxItems": 1, - "items": { - "$ref": "#/components/schemas/NetworkMount" - } - } - } - }, - "TemplateMounts": { - "type": "object", - "additionalProperties": false, - "description": "Storage mounts attached to a template. Templates support only a\nsingle persistent mount today; any `network` property is rejected\nwith 422 by the schema validator.\n\nPATCH semantics: omitting `mounts` or sending `{}` leaves the\nexisting mount unchanged.\n", - "properties": { - "persistent": { - "$ref": "#/components/schemas/PersistentMount" - } - } - }, - "PersistentMount": { - "type": "object", - "required": [ - "size", - "path" - ], - "additionalProperties": false, - "description": "Host-local persistent storage. Pinned to the pod's host machine — data\ndoes not survive a host failure. Disallowed on CPU pods. Mutually\nexclusive with NetworkMount. Deprecated: prefer NetworkMount for any\ndata you cannot recreate.\n", - "properties": { - "size": { - "type": "integer", - "minimum": 10, - "description": "Host-local persistent storage in GB. Upstream enforces a 10 GB floor.", - "example": 20 - }, - "path": { - "type": "string", - "description": "Mount path inside the container. May be changed via PATCH.", - "example": "/workspace" - } - } - }, - "NetworkMount": { - "type": "object", - "required": [ - "volumeId", - "path" - ], - "additionalProperties": false, - "description": "Reference to a NetworkVolume. Custom paths are honored at runtime on\nboth GPU and CPU pods. The underlying `volumeId` is immutable\npost-create; the mount `path` may be changed via PATCH.\n", - "properties": { - "volumeId": { - "type": "string", - "description": "ID of an existing NetworkVolume in the same data center as the pod.", - "example": "vol_xyz" - }, - "path": { - "type": "string", - "description": "Mount path inside the container. No default — must be specified explicitly.", - "example": "/runpod-volume" - } - } - }, - "GpuConfig": { - "type": "object", - "required": [ - "id" - ], - "properties": { - "id": { - "type": "string", - "description": "GPU type identifier", - "example": "NVIDIA GeForce RTX 4090" - }, - "count": { - "type": "integer", - "minimum": 1, - "default": 1, - "description": "Number of GPUs", - "example": 1 - } - } - }, - "CpuConfig": { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "CPU flavor identifier", - "example": "cpu5c" - }, - "count": { - "type": "integer", - "minimum": 1, - "description": "Number of vCPUs", - "example": 4 - } - } - }, - "Utilization": { - "type": "object", - "description": "Single-value utilization percentage (0–100). Shared by `cpu` and `memory`.", - "properties": { - "util": { - "type": "integer", - "example": 45 - } - } - }, - "PodGpuUtilization": { - "type": "object", - "description": "Per-GPU utilization metrics.", - "properties": { - "util": { - "type": "integer", - "example": 94 - }, - "memoryUtil": { - "type": "integer", - "example": 78 - } - } - }, - "PodRuntimePort": { - "type": "object", - "description": "Live port mapping for a running pod.", - "properties": { - "private": { - "type": "integer", - "example": 8888 - }, - "public": { - "type": "integer", - "nullable": true, - "example": 43210 - }, - "type": { - "type": "string", - "example": "http" - }, - "ip": { - "type": "string", - "nullable": true, - "example": "45.23.12.1" - } - } - }, - "PodRuntime": { - "type": "object", - "description": "Live utilization metrics for a running pod.", - "properties": { - "uptime": { - "type": "integer", - "description": "Seconds since the container started", - "example": 3600 - }, - "gpus": { - "type": "array", - "items": { - "$ref": "#/components/schemas/PodGpuUtilization" - } - }, - "cpu": { - "$ref": "#/components/schemas/Utilization" - }, - "memory": { - "$ref": "#/components/schemas/Utilization" - }, - "ports": { - "type": "array", - "items": { - "$ref": "#/components/schemas/PodRuntimePort" - } - } - } - }, - "PodStatus": { - "type": "string", - "description": "Lifecycle status of a pod.\n- `PROVISIONING` — pod is being allocated\n- `STARTING` — container is starting\n- `RUNNING` — container is healthy\n- `EXITED` — container exited (stopped)\n- `ERROR` — container is in an unrecoverable error state\n- `TERMINATED` — pod has been permanently deleted\n", - "enum": [ - "PROVISIONING", - "STARTING", - "RUNNING", - "EXITED", - "ERROR", - "TERMINATED" - ] - }, - "PodAction": { - "type": "string", - "description": "State transition to trigger on a pod.", - "enum": [ - "start", - "stop", - "restart", - "terminate" - ] - }, - "Cloud": { - "type": "string", - "description": "Cloud tier.\n- `SECURE` — RunPod-owned datacenter hardware\n- `COMMUNITY` — community-hosted hardware\n- `ALL` — eligible for either tier (request-only; responses always\n report the concrete tier the pod was placed on)\n", - "enum": [ - "SECURE", - "COMMUNITY", - "ALL" - ] - }, - "TemplateCategory": { - "type": "string", - "description": "Hardware family this template targets.\n- `CPU` — CPU-only workloads\n- `NVIDIA` — NVIDIA GPU workloads\n- `AMD` — AMD GPU workloads\n", - "enum": [ - "CPU", - "NVIDIA", - "AMD" - ] - }, - "Pod": { - "allOf": [ - { - "$ref": "#/components/schemas/ContainerConfig" - }, - { - "type": "object", - "required": [ - "id", - "name", - "status", - "actions", - "image", - "args", - "disk", - "mounts", - "ports", - "env", - "registry", - "gpu", - "cpu", - "cloud", - "dataCenter", - "template", - "cost", - "locked", - "tags", - "runtime", - "createdAt", - "startedAt" - ], - "properties": { - "id": { - "type": "string", - "example": "pod_abc123" - }, - "name": { - "type": "string", - "example": "my-training-pod" - }, - "status": { - "$ref": "#/components/schemas/PodStatus" - }, - "actions": { - "type": "array", - "description": "Valid state transitions for the current status.", - "items": { - "$ref": "#/components/schemas/PodAction" - } - }, - "mounts": { - "$ref": "#/components/schemas/Mounts" - }, - "gpu": { - "nullable": true, - "allOf": [ - { - "$ref": "#/components/schemas/GpuConfig" - } - ] - }, - "cpu": { - "nullable": true, - "allOf": [ - { - "$ref": "#/components/schemas/CpuConfig" - } - ] - }, - "cloud": { - "$ref": "#/components/schemas/Cloud" - }, - "dataCenter": { - "type": "string", - "nullable": true, - "description": "Data center where the pod is running (assigned by scheduler)", - "example": "US-TX-3" - }, - "template": { - "type": "string", - "nullable": true, - "description": "ID of the template this pod was created from", - "example": null - }, - "cost": { - "type": "number", - "format": "float", - "description": "Current cost in USD per hour (0.0 when EXITED or TERMINATED)", - "example": 0.35 - }, - "locked": { - "type": "boolean", - "description": "Whether the pod is locked (prevents stopping or resetting)", - "example": false - }, - "tags": { - "type": "object", - "additionalProperties": { - "type": "string" - }, - "description": "User-defined key-value labels", - "example": { - "project": "gpt-training" - } - }, - "runtime": { - "nullable": true, - "description": "Live utilization metrics. Null when the pod is not RUNNING.", - "allOf": [ - { - "$ref": "#/components/schemas/PodRuntime" - } - ] - }, - "createdAt": { - "type": "string", - "format": "date-time", - "example": "2026-03-13T20:00:00Z" - }, - "startedAt": { - "type": "string", - "format": "date-time", - "nullable": true, - "example": "2026-03-13T20:00:00Z" - } - } - } - ] - }, - "CreatePodRequest": { - "allOf": [ - { - "$ref": "#/components/schemas/ContainerConfig" - }, - { - "type": "object", - "required": [ - "name", - "image" - ], - "description": "Request body for creating a pod. Exactly one of `gpu` or `cpu`\nmust be set — enforced at the handler layer. CPU pod creation is\nstubbed pending AE-2991 and returns `501 Not Implemented`.\n", - "properties": { - "name": { - "type": "string", - "minLength": 1, - "example": "my-training-pod" - }, - "mounts": { - "$ref": "#/components/schemas/Mounts" - }, - "gpu": { - "$ref": "#/components/schemas/GpuConfig" - }, - "cpu": { - "$ref": "#/components/schemas/CpuConfig" - }, - "cloud": { - "$ref": "#/components/schemas/Cloud" - }, - "dataCenter": { - "type": "string", - "description": "Preferred data center for placement. The upstream scheduler\naccepts a single data center; pass null/omit to let the\nscheduler choose.\n", - "nullable": true, - "example": "US-TX-3" - } - } - } - ] - }, - "UpdatePodRequest": { - "allOf": [ - { - "$ref": "#/components/schemas/ContainerConfig" - }, - { - "type": "object", - "properties": { - "name": { - "type": "string", - "minLength": 1 - }, - "mounts": { - "$ref": "#/components/schemas/Mounts" - }, - "locked": { - "type": "boolean", - "description": "Lock the pod (true) or unlock it (false). Locked pods cannot be stopped or reset." - } - } - } - ] - }, - "PodActionRequest": { - "type": "object", - "required": [ - "action" - ], - "properties": { - "action": { - "$ref": "#/components/schemas/PodAction" - } - } - }, - "ListPodsResponse": { - "type": "object", - "required": [ - "pods" - ], - "properties": { - "pods": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Pod" - } - } - } - }, - "Template": { - "allOf": [ - { - "$ref": "#/components/schemas/ContainerConfig" - }, - { - "type": "object", - "required": [ - "id", - "name", - "image", - "args", - "disk", - "mounts", - "ports", - "env", - "registry", - "serverless", - "public", - "category" - ], - "properties": { - "id": { - "type": "string", - "example": "tpl_abc" - }, - "name": { - "type": "string", - "example": "My PyTorch Template" - }, - "mounts": { - "$ref": "#/components/schemas/TemplateMounts" - }, - "serverless": { - "type": "boolean", - "description": "Whether this template is for serverless workers (true) or pods (false)", - "example": false - }, - "public": { - "type": "boolean", - "description": "Whether this template is visible to other RunPod users", - "example": false - }, - "category": { - "$ref": "#/components/schemas/TemplateCategory" - } - } - } - ] - }, - "CreateTemplateRequest": { - "allOf": [ - { - "$ref": "#/components/schemas/ContainerConfig" - }, - { - "type": "object", - "required": [ - "name", - "image", - "category" - ], - "properties": { - "name": { - "type": "string", - "minLength": 1, - "example": "My PyTorch Template" - }, - "mounts": { - "$ref": "#/components/schemas/TemplateMounts" - }, - "serverless": { - "type": "boolean", - "default": false - }, - "public": { - "type": "boolean", - "default": false - }, - "category": { - "$ref": "#/components/schemas/TemplateCategory" - } - } - } - ] - }, - "UpdateTemplateRequest": { - "allOf": [ - { - "$ref": "#/components/schemas/ContainerConfig" - }, - { - "type": "object", - "properties": { - "name": { - "type": "string", - "minLength": 1 - }, - "mounts": { - "$ref": "#/components/schemas/TemplateMounts" - }, - "serverless": { - "type": "boolean" - }, - "public": { - "type": "boolean" - }, - "category": { - "$ref": "#/components/schemas/TemplateCategory" - } - } - } - ] - }, - "ListTemplatesResponse": { - "type": "object", - "required": [ - "templates" - ], - "properties": { - "templates": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Template" - } - } - } - }, - "Tag": { - "type": "object", - "required": [ - "id", - "key", - "value" - ], - "additionalProperties": false, - "properties": { - "id": { - "type": "string", - "description": "Tag identifier", - "example": "tag_abc123" - }, - "key": { - "type": "string", - "minLength": 1, - "description": "Tag key", - "example": "project" - }, - "value": { - "type": "string", - "minLength": 1, - "description": "Tag value", - "example": "gpt-training" - } - } - }, - "CreateTagRequest": { - "type": "object", - "required": [ - "key", - "value" - ], - "additionalProperties": false, - "properties": { - "key": { - "type": "string", - "minLength": 1, - "example": "project" - }, - "value": { - "type": "string", - "minLength": 1, - "example": "gpt-training" - } - } - }, - "UpdateTagRequest": { - "type": "object", - "minProperties": 1, - "additionalProperties": false, - "description": "At least one of `key` or `value` must be provided.", - "properties": { - "key": { - "type": "string", - "minLength": 1, - "example": "project" - }, - "value": { - "type": "string", - "minLength": 1, - "example": "gpt-training" - } - } - }, - "ListTagsResponse": { - "type": "object", - "required": [ - "tags" - ], - "additionalProperties": false, - "properties": { - "tags": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Tag" - } - } - } - }, - "NetworkVolume": { - "type": "object", - "required": [ - "id", - "name", - "size", - "dataCenter" - ], - "properties": { - "id": { - "type": "string", - "description": "Unique network volume identifier", - "example": "agv6w2qcg7" - }, - "name": { - "type": "string", - "description": "Human-readable name (not required to be unique)", - "example": "my-dataset" - }, - "size": { - "type": "integer", - "minimum": 1, - "maximum": 4000, - "description": "Allocated storage in GB", - "example": 50 - }, - "dataCenter": { - "type": "string", - "description": "Data center location; immutable after creation", - "example": "EU-RO-1" - } - } - }, - "CreateNetworkVolumeRequest": { - "type": "object", - "required": [ - "name", - "size", - "dataCenter" - ], - "properties": { - "name": { - "type": "string", - "minLength": 1, - "description": "Human-readable name", - "example": "my-dataset" - }, - "size": { - "type": "integer", - "minimum": 1, - "maximum": 4000, - "description": "Storage to allocate in GB", - "example": 50 - }, - "dataCenter": { - "type": "string", - "minLength": 1, - "description": "Data center in which to create the volume", - "example": "EU-RO-1" - } - } - }, - "UpdateNetworkVolumeRequest": { - "type": "object", - "description": "All fields are optional. Only provided fields are updated.", - "properties": { - "name": { - "type": "string", - "minLength": 1, - "description": "New human-readable name", - "example": "renamed-volume" - }, - "size": { - "type": "integer", - "minimum": 1, - "maximum": 4000, - "description": "New size in GB. Must be greater than or equal to the current size —\nnetwork volume storage cannot be reduced.\n", - "example": 100 - } - } - }, - "ListNetworkVolumesResponse": { - "type": "object", - "required": [ - "networkVolumes" - ], - "properties": { - "networkVolumes": { - "type": "array", - "items": { - "$ref": "#/components/schemas/NetworkVolume" - } - } - } - }, - "Registry": { - "type": "object", - "required": [ - "id", - "name" - ], - "properties": { - "id": { - "type": "string", - "example": "reg_abc" - }, - "name": { - "type": "string", - "example": "my-private-registry" - } - } - }, - "CreateRegistryRequest": { - "type": "object", - "required": [ - "name", - "username", - "password" - ], - "properties": { - "name": { - "type": "string", - "minLength": 1, - "example": "my-private-registry" - }, - "username": { - "type": "string", - "minLength": 1, - "description": "Registry username (write-only, not returned in responses)" - }, - "password": { - "type": "string", - "minLength": 1, - "description": "Registry password (write-only, not returned in responses)" - } - } - }, - "ListRegistriesResponse": { - "type": "object", - "required": [ - "registries" - ], - "properties": { - "registries": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Registry" - } - } - } - }, - "Repository": { - "type": "object", - "description": "A project namespace that holds one or more images.", - "properties": { - "name": { - "type": "string", - "description": "Repository name (lowercase, [a-z0-9_-]).", - "example": "my-app" - }, - "created_at": { - "type": "string", - "format": "date-time" - } - } - }, - "CreateRepositoryRequest": { - "type": "object", - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string", - "description": "Repository name; must be unique within your account.", - "example": "my-app" - } - } - }, - "ListRepositoriesResponse": { - "type": "object", - "required": [ - "repositories" - ], - "properties": { - "repositories": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Repository" - } - } - } - }, - "Image": { - "type": "object", - "description": "A named container image within a repository. Builds push versions of this image as `/:v`.", - "properties": { - "name": { - "type": "string", - "description": "Image name (lowercase, [a-z0-9_-]).", - "example": "api" - }, - "next_version": { - "type": "integer", - "description": "The version that will be assigned to the next build of this image.", - "example": 3 - }, - "created_at": { - "type": "string", - "format": "date-time" - }, - "versions": { - "type": "array", - "description": "Pullable image URLs for every successful build of this image, ordered oldest to newest. Empty until the first build succeeds.", - "items": { - "type": "string" - }, - "example": [ - "registry.example.com/user-abc/my-app/api:v1", - "registry.example.com/user-abc/my-app/api:v2" - ] - } - } - }, - "CreateImageRequest": { - "type": "object", - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string", - "description": "Image name; must be unique within the repository.", - "example": "api" - } - } - }, - "ListImagesResponse": { - "type": "object", - "required": [ - "images" - ], - "properties": { - "images": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Image" - } - } - } - }, - "Build": { - "type": "object", - "description": "A single build job for a specific image.", - "properties": { - "id": { - "type": "string", - "example": "build_01HWZ4..." - }, - "version": { - "type": "integer", - "description": "Auto-assigned monotonic version for this image. The build is always pushed to `/:v`.", - "example": 3 - }, - "status": { - "type": "string", - "enum": [ - "queued", - "running", - "succeeded", - "failed", - "cancelled" - ], - "example": "queued" - }, - "image": { - "type": "string", - "description": "Fully-qualified pullable image URL. Use this directly with `docker pull`.", - "example": "registry.example.com/user-abc/my-app/api:v3" - }, - "result_digest": { - "type": "string", - "nullable": true, - "description": "Image digest, set when status is `succeeded`.", - "example": "sha256:abc..." - }, - "failure_reason": { - "type": "string", - "nullable": true - }, - "source": { - "description": "The source spec the build was submitted with. Same shape as `CreateBuildRequest.source`.", - "oneOf": [ - { - "$ref": "#/components/schemas/GitSource" - }, - { - "$ref": "#/components/schemas/InlineSource" - } - ], - "discriminator": { - "propertyName": "type", - "mapping": { - "git": "#/components/schemas/GitSource", - "inline": "#/components/schemas/InlineSource" - } - } - }, - "dockerfile_path": { - "type": "string" - }, - "build_args": { - "type": "object", - "additionalProperties": { - "type": "string" - } - }, - "target_stage": { - "type": "string", - "nullable": true - }, - "queued_at": { - "type": "string", - "format": "date-time" - }, - "started_at": { - "type": "string", - "format": "date-time", - "nullable": true - }, - "finished_at": { - "type": "string", - "format": "date-time", - "nullable": true - } - } - }, - "GitSource": { - "type": "object", - "description": "Build context cloned from a git URL.", - "required": [ - "type", - "url" - ], - "properties": { - "type": { - "type": "string", - "enum": [ - "git" - ] - }, - "url": { - "type": "string", - "description": "HTTPS git URL.", - "example": "https://github.com/user/repo" - }, - "ref": { - "type": "string", - "description": "Branch, tag, or commit. Defaults to the repository's default branch.", - "example": "main" - } - } - }, - "InlineSource": { - "type": "object", - "description": "Build context defined inline — a Dockerfile body, no surrounding files.", - "required": [ - "type", - "dockerfile_content" - ], - "properties": { - "type": { - "type": "string", - "enum": [ - "inline" - ] - }, - "dockerfile_content": { - "type": "string", - "description": "Dockerfile contents to build.", - "example": "FROM alpine:3.20\nCMD [\"echo\", \"hello\"]\n" - } - } - }, - "CreateBuildRequest": { - "type": "object", - "required": [ - "source" - ], - "properties": { - "source": { - "description": "Where the build context comes from.", - "oneOf": [ - { - "$ref": "#/components/schemas/GitSource" - }, - { - "$ref": "#/components/schemas/InlineSource" - } - ], - "discriminator": { - "propertyName": "type", - "mapping": { - "git": "#/components/schemas/GitSource", - "inline": "#/components/schemas/InlineSource" - } - } - }, - "dockerfile_path": { - "type": "string", - "description": "Path to the Dockerfile within the source. Defaults to `Dockerfile` at the source root.", - "example": "Dockerfile" - }, - "build_args": { - "type": "object", - "additionalProperties": { - "type": "string" - }, - "description": "Docker `--build-arg` values." - }, - "target_stage": { - "type": "string", - "nullable": true, - "description": "For multi-stage Dockerfiles, the stage to build (Docker `--target`). Omit to build the final stage." - } - } - }, - "ListBuildsResponse": { - "type": "object", - "required": [ - "builds" - ], - "properties": { - "builds": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Build" - } - } - } - }, - "GpuType": { - "type": "object", - "required": [ - "id", - "name", - "pool", - "manufacturer", - "memory", - "secure", - "community", - "price", - "maxCount" - ], - "properties": { - "id": { - "type": "string", - "description": "Individual GPU type identifier (use for pod creation)", - "example": "NVIDIA GeForce RTX 4090" - }, - "name": { - "type": "string", - "example": "RTX 4090" - }, - "pool": { - "type": "string", - "nullable": true, - "description": "Serverless GPU pool ID (use for endpoint creation). Null if GPU is not in a serverless pool.", - "example": "ADA_24" - }, - "manufacturer": { - "type": "string", - "example": "NVIDIA" - }, - "memory": { - "type": "integer", - "description": "VRAM in GB", - "example": 24 - }, - "secure": { - "type": "boolean", - "description": "Available on secure cloud", - "example": true - }, - "community": { - "type": "boolean", - "description": "Available on community cloud", - "example": true - }, - "price": { - "type": "object", - "required": [ - "secure", - "community" - ], - "properties": { - "secure": { - "type": "number", - "format": "float", - "example": 0.44 - }, - "community": { - "type": "number", - "format": "float", - "example": 0.31 - } - } - }, - "maxCount": { - "type": "object", - "required": [ - "secure", - "community" - ], - "properties": { - "secure": { - "type": "integer", - "example": 8 - }, - "community": { - "type": "integer", - "example": 4 - } - } - }, - "availability": { - "description": "Overall GPU availability. Present only when requested with include=availability.", - "$ref": "#/components/schemas/AvailabilityLevel" - }, - "dataCenters": { - "type": "array", - "description": "Per-datacenter GPU availability. Present only when requested with include=availability.", - "items": { - "$ref": "#/components/schemas/DataCenterAvailability" - } - } - } - }, - "AvailabilityLevel": { - "type": "string", - "description": "Catalog stock availability level.", - "enum": [ - "NONE", - "LOW", - "MEDIUM", - "HIGH" - ] - }, - "CatalogResourceAvailability": { - "type": "object", - "required": [ - "id", - "name", - "availability" - ], - "properties": { - "id": { - "type": "string", - "description": "Catalog resource identifier.", - "example": "NVIDIA GeForce RTX 4090" - }, - "name": { - "type": "string", - "description": "Human-readable catalog resource name.", - "example": "RTX 4090" - }, - "availability": { - "$ref": "#/components/schemas/AvailabilityLevel" - } - } - }, - "DataCenterAvailability": { - "type": "object", - "required": [ - "id", - "name", - "availability" - ], - "properties": { - "id": { - "type": "string", - "description": "Data center identifier.", - "example": "US-CA-2" - }, - "name": { - "type": "string", - "description": "Human-readable data center name.", - "example": "US California 2" - }, - "availability": { - "$ref": "#/components/schemas/AvailabilityLevel" - } - } - }, - "ListGpuTypesResponse": { - "type": "object", - "required": [ - "gpus" - ], - "properties": { - "gpus": { - "type": "array", - "items": { - "$ref": "#/components/schemas/GpuType" - } - } - } - }, - "CpuType": { - "type": "object", - "required": [ - "id", - "name", - "group", - "vcpu", - "ramGbPerVcpu" - ], - "properties": { - "id": { - "type": "string", - "description": "CPU flavor identifier (use in cpu.id for pod creation)", - "example": "cpu5c" - }, - "name": { - "type": "string", - "description": "Human-readable flavor name", - "example": "Compute-Optimized" - }, - "group": { - "type": "string", - "description": "CPU generation group", - "example": "Gen 5" - }, - "vcpu": { - "type": "object", - "required": [ - "min", - "max" - ], - "properties": { - "min": { - "type": "integer", - "example": 2 - }, - "max": { - "type": "integer", - "example": 32 - } - } - }, - "ramGbPerVcpu": { - "type": "number", - "format": "float", - "description": "GB of RAM allocated per vCPU. Multiply by the chosen vCPU\ncount (within `vcpu.min`..`vcpu.max`) to get the total RAM\nfor an instance of this flavor. May be fractional.\n", - "example": 2.5 - } - } - }, - "ListCpuTypesResponse": { - "type": "object", - "required": [ - "cpus" - ], - "properties": { - "cpus": { - "type": "array", - "items": { - "$ref": "#/components/schemas/CpuType" - } - } - } - }, - "DataCenter": { - "type": "object", - "required": [ - "id", - "name", - "region", - "volumes", - "compliance" - ], - "properties": { - "id": { - "type": "string", - "example": "US-TX-3" - }, - "name": { - "type": "string", - "example": "US Texas 3" - }, - "region": { - "$ref": "#/components/schemas/DataCenterRegion" - }, - "volumes": { - "type": "boolean", - "description": "Whether this data center supports network volumes", - "example": true - }, - "compliance": { - "type": "array", - "description": "Compliance certifications held by this data center", - "items": { - "$ref": "#/components/schemas/Compliance" - }, - "example": [ - "GDPR", - "ISO_IEC_27001", - "SOC_2_TYPE_2" - ] - }, - "gpuAvailability": { - "type": "array", - "description": "Per-GPU availability in this data center. Present only when requested with include=gpuAvailability.", - "items": { - "$ref": "#/components/schemas/CatalogResourceAvailability" - } - } - } - }, - "DataCenterRegion": { - "type": "string", - "description": "Continental region containing the data center.", - "example": "EUROPE", - "enum": [ - "NORTH_AMERICA", - "SOUTH_AMERICA", - "EUROPE", - "ASIA", - "MIDDLE_EAST", - "AFRICA", - "OCEANIA", - "ANTARCTICA", - "UNKNOWN" - ] - }, - "Compliance": { - "type": "string", - "description": "Compliance certifications.", - "enum": [ - "GDPR", - "ISO_IEC_27001", - "ISO_14001", - "PCI_DSS", - "HITRUST", - "SOC_1_TYPE_2", - "SOC_2_TYPE_2", - "SOC_3_TYPE_2", - "ITAR", - "FISMA_HIGH", - "HIPAA", - "RENEWABLE" - ] - }, - "ListDataCentersResponse": { - "type": "object", - "required": [ - "dataCenters" - ], - "properties": { - "dataCenters": { - "type": "array", - "items": { - "$ref": "#/components/schemas/DataCenter" - } - } - } - }, - "ErrorResponse": { - "type": "object", - "properties": { - "title": { - "type": "string", - "description": "Short human-readable summary", - "example": "Not Found" - }, - "status": { - "type": "integer", - "description": "HTTP status code", - "example": 404 - }, - "detail": { - "type": "string", - "description": "Human-readable explanation", - "example": "pod not found" - } - } - }, - "ValidatationErrorResponse": { - "type": "object", - "properties": { - "title": { - "type": "string", - "description": "Short human-readable summary", - "example": "Unprocessable Entity" - }, - "status": { - "type": "integer", - "description": "HTTP status code", - "example": 422 - }, - "errors": { - "type": "array", - "items": { - "type": "string", - "example": "$: minProperties: got 0, want 1" - }, - "description": "Human-readable explanation" - } - } - } - } - }, - "paths": { - "/v2/pods": { - "get": { - "operationId": "listPods", - "summary": "List pods", - "description": "Returns all pods owned by the authenticated user.", - "tags": [ - "Pods" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ListPodsResponse" - } - } - } - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - }, - "post": { - "operationId": "createPod", - "summary": "Create a pod", - "description": "Creates a new pod. Specify `gpu` for compute.\nContainerConfig fields can be spread from a template response.\n", - "tags": [ - "Pods" - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CreatePodRequest" - } - } - } - }, - "responses": { - "201": { - "description": "Created", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Pod" - } - } - } - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - } - }, - "/v2/pods/{id}": { - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - }, - "description": "Pod identifier", - "example": "pod_abc123" - } - ], - "get": { - "operationId": "getPod", - "summary": "Get a pod", - "description": "Returns a single pod by ID.", - "tags": [ - "Pods" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Pod" - } - } - } - }, - "404": { - "description": "Pod not found", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - }, - "patch": { - "operationId": "updatePod", - "summary": "Update a pod", - "description": "Updates pod configuration. Only provided fields are changed.", - "tags": [ - "Pods" - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/UpdatePodRequest" - } - } - } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Pod" - } - } - } - }, - "404": { - "description": "Pod not found", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - }, - "delete": { - "operationId": "deletePod", - "summary": "Terminate a pod", - "description": "Permanently terminates and deletes a pod.", - "tags": [ - "Pods" - ], - "responses": { - "204": { - "description": "Terminated" - }, - "404": { - "description": "Pod not found", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - } - }, - "/v2/pods/{id}/action": { - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - }, - "example": "pod_abc123" - } - ], - "post": { - "operationId": "podAction", - "summary": "Trigger a pod state transition", - "description": "Triggers a state transition on a pod. Valid actions depend on the current status\nand are listed in the pod's `actions` field.\n", - "tags": [ - "Pods" - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/PodActionRequest" - } - } - } - }, - "responses": { - "200": { - "description": "Action applied — returns updated pod", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Pod" - } - } - } - }, - "204": { - "description": "Pod terminated (for action=terminate)" - }, - "404": { - "description": "Pod not found", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "409": { - "description": "Action not valid for current pod status", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - } - }, - "/v2/templates": { - "get": { - "operationId": "listTemplates", - "summary": "List templates", - "description": "Returns all templates owned by the authenticated user.", - "tags": [ - "Templates" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ListTemplatesResponse" - } - } - } - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - }, - "post": { - "operationId": "createTemplate", - "summary": "Create a template", - "tags": [ - "Templates" - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CreateTemplateRequest" - } - } - } - }, - "responses": { - "201": { - "description": "Created", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Template" - } - } - } - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - } - }, - "/v2/templates/{id}": { - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - }, - "example": "tpl_abc" - } - ], - "get": { - "operationId": "getTemplate", - "summary": "Get a template", - "tags": [ - "Templates" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Template" - } - } - } - }, - "404": { - "description": "Template not found", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - }, - "patch": { - "operationId": "updateTemplate", - "summary": "Update a template", - "description": "Updates template configuration. Only provided fields are changed.", - "tags": [ - "Templates" - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/UpdateTemplateRequest" - } - } - } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Template" - } - } - } - }, - "404": { - "description": "Template not found", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - }, - "delete": { - "operationId": "deleteTemplate", - "summary": "Delete a template", - "tags": [ - "Templates" - ], - "responses": { - "204": { - "description": "Deleted" - }, - "404": { - "description": "Template not found", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - } - }, - "/v2/tags": { - "get": { - "operationId": "listTags", - "summary": "List tags", - "description": "Returns all tags owned by the authenticated user.", - "tags": [ - "Tags" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ListTagsResponse" - } - } - } - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - }, - "post": { - "operationId": "createTag", - "summary": "Create a tag", - "description": "Creates a user-defined key-value tag.", - "tags": [ - "Tags" - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CreateTagRequest" - } - } - } - }, - "responses": { - "201": { - "description": "Created", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Tag" - } - } - } - }, - "400": { - "description": "Invalid request body", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - } - }, - "/v2/tags/{id}": { - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - }, - "description": "Tag identifier", - "example": "tag_abc123" - } - ], - "get": { - "operationId": "getTag", - "summary": "Get a tag", - "description": "Returns a single tag by ID.", - "tags": [ - "Tags" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Tag" - } - } - } - }, - "404": { - "description": "Tag not found", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - }, - "patch": { - "operationId": "updateTag", - "summary": "Update a tag", - "description": "Updates a tag. At least one of `key` or `value` must be provided.", - "tags": [ - "Tags" - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/UpdateTagRequest" - } - } - } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Tag" - } - } - } - }, - "404": { - "description": "Tag not found", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "422": { - "description": "Unprocessable request body (missing `key` and/or `value`)", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - }, - "delete": { - "operationId": "deleteTag", - "summary": "Delete a tag", - "description": "Deletes a tag.", - "tags": [ - "Tags" - ], - "responses": { - "204": { - "description": "Deleted" - }, - "404": { - "description": "Tag not found", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - } - }, - "/v2/network-volumes": { - "get": { - "operationId": "listNetworkVolumes", - "summary": "List network volumes", - "description": "Returns all network volumes owned by the authenticated user.", - "tags": [ - "Network Volumes" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ListNetworkVolumesResponse" - } - } - } - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - }, - "post": { - "operationId": "createNetworkVolume", - "summary": "Create a network volume", - "description": "Provisions a new network volume in the specified data center.", - "tags": [ - "Network Volumes" - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CreateNetworkVolumeRequest" - } - } - } - }, - "responses": { - "201": { - "description": "Created", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/NetworkVolume" - } - } - } - }, - "400": { - "description": "Invalid request body", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - } - }, - "/v2/network-volumes/{id}": { - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - }, - "description": "Network volume identifier", - "example": "agv6w2qcg7" - } - ], - "get": { - "operationId": "getNetworkVolume", - "summary": "Get a network volume", - "description": "Returns a single network volume by ID.", - "tags": [ - "Network Volumes" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/NetworkVolume" - } - } - } - }, - "404": { - "description": "Network volume not found", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - }, - "patch": { - "operationId": "updateNetworkVolume", - "summary": "Update a network volume", - "description": "Updates mutable fields on a network volume. Only provided fields are changed.\nNote: `size` may only increase; attempts to reduce size will be rejected.\n", - "tags": [ - "Network Volumes" - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/UpdateNetworkVolumeRequest" - } - } - } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/NetworkVolume" - } - } - } - }, - "400": { - "description": "Invalid request body or size decrease attempted", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "404": { - "description": "Network volume not found", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - }, - "delete": { - "operationId": "deleteNetworkVolume", - "summary": "Delete a network volume", - "description": "Permanently deletes a network volume and releases its storage.", - "tags": [ - "Network Volumes" - ], - "responses": { - "204": { - "description": "Deleted" - }, - "404": { - "description": "Network volume not found", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - } - }, - "/v2/registries": { - "get": { - "operationId": "listRegistries", - "summary": "List container registries", - "description": "Returns all container registry credentials owned by the authenticated user.", - "tags": [ - "Registries" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ListRegistriesResponse" - } - } - } - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - }, - "post": { - "operationId": "createRegistry", - "summary": "Create a container registry credential", - "description": "Stores credentials for a private container registry. Credentials are write-only.", - "tags": [ - "Registries" - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CreateRegistryRequest" - } - } - } - }, - "responses": { - "201": { - "description": "Created", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Registry" - } - } - } - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - } - }, - "/v2/registries/{id}": { - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - }, - "example": "reg_abc" - } - ], - "get": { - "operationId": "getRegistry", - "summary": "Get a container registry credential", - "tags": [ - "Registries" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Registry" - } - } - } - }, - "404": { - "description": "Registry not found", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - }, - "delete": { - "operationId": "deleteRegistry", - "summary": "Delete a container registry credential", - "tags": [ - "Registries" - ], - "responses": { - "204": { - "description": "Deleted" - }, - "404": { - "description": "Registry not found", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - } - }, - "/v2/catalog/gpus": { - "get": { - "operationId": "listGpuTypes", - "summary": "List GPU types", - "description": "Returns available GPU types with pricing. Availability is included only when requested with include=availability.", - "tags": [ - "Catalog" - ], - "parameters": [ - { - "name": "include", - "in": "query", - "required": false, - "description": "Comma-separated optional expansions. Supported value: availability.", - "schema": { - "type": "string", - "example": "availability" - } - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ListGpuTypesResponse" - } - } - } - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - } - }, - "/v2/catalog/gpus/{id}": { - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - }, - "example": "NVIDIA GeForce RTX 4090" - } - ], - "get": { - "operationId": "getGpuType", - "summary": "Get a GPU type", - "description": "Returns a single GPU type with pricing. Availability details are included only when requested with include=availability.", - "tags": [ - "Catalog" - ], - "parameters": [ - { - "name": "include", - "in": "query", - "required": false, - "description": "Comma-separated optional expansions. Supported value: availability.", - "schema": { - "type": "string", - "example": "availability" - } - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/GpuType" - } - } - } - }, - "404": { - "description": "GPU type not found", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - } - }, - "/v2/catalog/cpus": { - "get": { - "operationId": "listCpuTypes", - "summary": "List CPU types", - "description": "Returns available CPU flavors.", - "tags": [ - "Catalog" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ListCpuTypesResponse" - } - } - } - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - } - }, - "/v2/catalog/datacenters": { - "get": { - "operationId": "listDataCenters", - "summary": "List data centers", - "description": "Returns available data center locations.", - "tags": [ - "Catalog" - ], - "parameters": [ - { - "name": "include", - "in": "query", - "required": false, - "description": "Comma-separated optional expansions. Supported value: gpuAvailability.", - "schema": { - "type": "string", - "example": "gpuAvailability" - } - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ListDataCentersResponse" - } - } - } - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - } - }, - "/v2/repositories": { - "get": { - "operationId": "listRepositories", - "summary": "List repositories", - "tags": [ - "Builds" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ListRepositoriesResponse" - } - } - } - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - }, - "post": { - "operationId": "createRepository", - "summary": "Create a repository", - "tags": [ - "Builds" - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CreateRepositoryRequest" - } - } - } - }, - "responses": { - "201": { - "description": "Created", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Repository" - } - } - } - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - } - }, - "/v2/repositories/{repo_name}": { - "parameters": [ - { - "name": "repo_name", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - } - ], - "delete": { - "operationId": "deleteRepository", - "summary": "Delete a repository", - "description": "Without `?purge=true`, the repository must be empty (no images) or the response is 409 with `code=repository_not_empty`. With `?purge=true`, cascades through all images and builds under the repository; any active builds are cancelled in the same transaction before deletion.\n", - "tags": [ - "Builds" - ], - "parameters": [ - { - "name": "purge", - "in": "query", - "required": false, - "schema": { - "type": "boolean", - "default": false - }, - "description": "When true, cascade-deletes images and builds (cancelling any active builds) instead of refusing on non-empty.\n" - } - ], - "responses": { - "204": { - "description": "Deleted" - }, - "404": { - "description": "Repository not found (or owned by another user)", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "409": { - "description": "Repository has images and purge was not set", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - } - }, - "/v2/repositories/{repo_name}/images": { - "parameters": [ - { - "name": "repo_name", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - } - ], - "get": { - "operationId": "listImages", - "summary": "List images in a repository", - "tags": [ - "Builds" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ListImagesResponse" - } - } - } - }, - "404": { - "description": "Repository not found", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - }, - "post": { - "operationId": "createImage", - "summary": "Create an image in a repository", - "tags": [ - "Builds" - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CreateImageRequest" - } - } - } - }, - "responses": { - "201": { - "description": "Created", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Image" - } - } - } - }, - "404": { - "description": "Repository not found", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - } - }, - "/v2/repositories/{repo_name}/images/{image_name}": { - "parameters": [ - { - "name": "repo_name", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - }, - { - "name": "image_name", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - } - ], - "get": { - "operationId": "getImage", - "summary": "Get an image", - "tags": [ - "Builds" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Image" - } - } - } - }, - "404": { - "description": "Image not found", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - }, - "delete": { - "operationId": "deleteImage", - "summary": "Delete an image", - "description": "Without `?purge=true`, the image must have no builds or the response is 409 with `code=image_not_empty`. With `?purge=true`, cascade-deletes all builds (cancelling any that are active).\n", - "tags": [ - "Builds" - ], - "parameters": [ - { - "name": "purge", - "in": "query", - "required": false, - "schema": { - "type": "boolean", - "default": false - } - } - ], - "responses": { - "204": { - "description": "Deleted" - }, - "404": { - "description": "Image not found (or owned by another user)", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "409": { - "description": "Image has builds and purge was not set", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - } - }, - "/v2/repositories/{repo_name}/images/{image_name}/builds": { - "parameters": [ - { - "name": "repo_name", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - }, - { - "name": "image_name", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - } - ], - "get": { - "operationId": "listBuilds", - "summary": "List builds for an image", - "tags": [ - "Builds" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ListBuildsResponse" - } - } - } - }, - "404": { - "description": "Image not found", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - }, - "post": { - "operationId": "createBuild", - "summary": "Submit a build for an image", - "description": "Queues a build. The build runs asynchronously; poll `GET /v2/builds/{id}` (or list builds for this image) until status is `succeeded` or `failed`. Pass `Idempotency-Key` to safely retry network failures.\n", - "tags": [ - "Builds" - ], - "parameters": [ - { - "in": "header", - "name": "Idempotency-Key", - "required": false, - "schema": { - "type": "string" - }, - "description": "Client-supplied key. Repeating with the same key returns the existing build." - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CreateBuildRequest" - } - } - } - }, - "responses": { - "200": { - "description": "Existing build returned (idempotency-key match)", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Build" - } - } - } - }, - "201": { - "description": "Build created", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Build" - } - } - } - }, - "404": { - "description": "Image not found", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - } - }, - "/v2/builds/{id}": { - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - }, - "example": "build_abc" - } - ], - "get": { - "operationId": "getBuild", - "summary": "Get a build by id", - "tags": [ - "Builds" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Build" - } - } - } - }, - "404": { - "description": "Build not found", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - }, - "delete": { - "operationId": "deleteBuild", - "summary": "Delete (and cancel, if active) a build", - "description": "Deletes the build resource. If the build is currently in an active state (queued or running), it is transitioned to `cancelled` in the same transaction before removal — the builder learns from a status poll and aborts buildctl.\n", - "tags": [ - "Builds" - ], - "responses": { - "204": { - "description": "Deleted" - }, - "404": { - "description": "Build not found (or owned by another user)", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - } - }, - "/v2/builds/{id}/cancel": { - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - }, - "example": "build_abc" - } - ], - "post": { - "operationId": "cancelBuild", - "summary": "Cancel a build", - "description": "Cancels a queued or running build. Idempotent — cancelling an already-cancelled build returns it unchanged. Returns 409 if the build already reached a terminal state (`success` or `failed`). The running build execution is stopped asynchronously by the scheduler; the build transitions to `cancelled` immediately.\n", - "tags": [ - "Builds" - ], - "responses": { - "200": { - "description": "Build cancelled (or already cancelled)", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Build" - } - } - } - }, - "404": { - "description": "Build not found (or owned by another user)", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "409": { - "description": "Build already reached a terminal state", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - } - }, - "/v2/builds/{id}/logs": { - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - }, - "example": "build_abc" - } - ], - "get": { - "operationId": "getBuildLogs", - "summary": "Fetch the build log", - "description": "Returns the captured stdout+stderr of the build. By default (`follow=false`), responds with a `text/plain` snapshot of whatever has been captured so far and closes the connection — poll to see content grow while a build is running.\n\nWith `?follow=true`, the response is a Server-Sent Events stream: the server holds the connection open and pushes `data:` events as new content arrives, then emits a final `event: end` and closes when the build terminates.\n", - "tags": [ - "Builds" - ], - "parameters": [ - { - "name": "follow", - "in": "query", - "required": false, - "schema": { - "type": "boolean", - "default": false - }, - "description": "When true, stream new log content as Server-Sent Events instead of returning a snapshot." - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "text/plain": { - "schema": { - "type": "string", - "description": "Snapshot of the current build log. Returned when `follow=false` or the param is absent." - } - }, - "text/event-stream": { - "schema": { - "type": "string", - "description": "SSE stream. Each new chunk of log content is emitted as one or more\n`data: ` events (one per log line; lines reassemble by joining with `\\n`).\nWhen the build reaches a terminal state, the server emits `event: end\\ndata: \\n\\n` and closes.\n" - } - } - } - }, - "404": { - "description": "Build not found", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - } - } - } -} \ No newline at end of file From f6194abf75f60c2d5b48dda5ce5d129c1e80fcf9 Mon Sep 17 00:00:00 2001 From: lgunreddi Date: Thu, 25 Jun 2026 14:57:42 -0400 Subject: [PATCH 06/41] Add files via upload --- api-reference-v2/openapi.json | 5040 +++++++++++++++++++++++++++++++++ 1 file changed, 5040 insertions(+) create mode 100644 api-reference-v2/openapi.json diff --git a/api-reference-v2/openapi.json b/api-reference-v2/openapi.json new file mode 100644 index 00000000..1415e01e --- /dev/null +++ b/api-reference-v2/openapi.json @@ -0,0 +1,5040 @@ +{ + "openapi": "3.0.3", + "info": { + "title": "RunPod REST API", + "version": "2.0.0", + "description": "RunPod public REST API — v2" + }, + "servers": [ + { + "url": "/", + "description": "Current server" + } + ], + "security": [ + { + "bearerAuth": [] + } + ], + "components": { + "securitySchemes": { + "bearerAuth": { + "type": "http", + "scheme": "bearer", + "bearerFormat": "RunPod API Key" + } + }, + "parameters": { + "BillingStartTime": { + "name": "startTime", + "in": "query", + "required": false, + "description": "Start of the billing period (RFC 3339). Defaults to 30 days ago. Snapped down to the start of its bucketSize bucket so the window aligns with the returned records; provide a boundary-aligned value (e.g. midnight for bucketSize=day) to avoid widening.\n", + "schema": { + "type": "string", + "format": "date-time" + }, + "example": "2026-05-01T00:00:00Z" + }, + "BillingEndTime": { + "name": "endTime", + "in": "query", + "required": false, + "description": "End of the billing period (RFC 3339), exclusive. Defaults to now. Snapped up to the end of the bucketSize bucket it lands in (unless already on a boundary) so the window aligns with the returned records.\n", + "schema": { + "type": "string", + "format": "date-time" + }, + "example": "2026-06-01T00:00:00Z" + }, + "BillingBucketSize": { + "name": "bucketSize", + "in": "query", + "required": false, + "description": "Length of each billing time bucket. Defaults to day.", + "schema": { + "$ref": "#/components/schemas/BillingBucketSize" + } + }, + "BillingLastN": { + "name": "lastN", + "in": "query", + "required": false, + "description": "Return the last N buckets of bucketSize, ending with the current (in-progress) bucket — e.g. lastN=100 with bucketSize=day is \"last 100 days\". The resolved window is aligned to bucket boundaries: startTime is the start of the earliest bucket (e.g. midnight of the earliest day) and endTime is the end of the current bucket. Mutually exclusive with startTime/endTime; provide one or the other, not both.\n", + "schema": { + "type": "integer", + "minimum": 1 + }, + "example": 30 + }, + "CatalogIncludeParam": { + "name": "include", + "in": "query", + "required": false, + "description": "Comma-separated optional expansions. Supported value today: AVAILABILITY. This may expand with more include values in the future.", + "style": "form", + "explode": false, + "schema": { + "type": "array", + "maxItems": 1, + "items": { + "$ref": "#/components/schemas/CatalogInclude" + } + }, + "example": [ + "AVAILABILITY" + ] + }, + "GpuProductFilter": { + "name": "product", + "in": "query", + "required": false, + "description": "Comma-separated availability product contexts. Supported values: POD, CLUSTER, SERVERLESS. Valid only with include=AVAILABILITY. Upstream default when omitted: POD.", + "style": "form", + "explode": false, + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Product" + } + }, + "example": [ + "POD", + "SERVERLESS" + ] + }, + "GpuCountFilter": { + "name": "count", + "in": "query", + "required": false, + "description": "GPU count for availability and lowest-price calculations. Valid only with include=AVAILABILITY. Defaults to 1.", + "schema": { + "type": "integer", + "minimum": 1, + "default": 1 + }, + "example": 2 + }, + "GpuCloudFilter": { + "name": "cloud", + "in": "query", + "required": false, + "description": "Cloud type for availability and lowest-price calculations. Valid only with include=AVAILABILITY. Supported values: SECURE, COMMUNITY. Upstream default when omitted: SECURE.", + "schema": { + "$ref": "#/components/schemas/GpuCloudFilter" + } + }, + "MinCudaVersionFilter": { + "name": "minCudaVersion", + "in": "query", + "required": false, + "description": "Minimum CUDA version for availability and lowest-price calculations. Valid only with include=AVAILABILITY. Format: integer major or major.minor, e.g. 12 or 12.1.", + "schema": { + "type": "string" + }, + "example": "12.1" + }, + "CpuProductFilter": { + "name": "product", + "in": "query", + "required": false, + "description": "Availability product context. Valid only with include=AVAILABILITY. Supported values for CPUs: POD, SERVERLESS. Upstream default when omitted: POD.", + "schema": { + "$ref": "#/components/schemas/CpuProduct" + } + }, + "CpuVCPUCountFilter": { + "name": "vcpuCount", + "in": "query", + "required": false, + "description": "Availability vCPU count. Valid only with include=AVAILABILITY. Must be a power of two.", + "schema": { + "type": "integer", + "minimum": 2 + }, + "example": 4 + } + }, + "schemas": { + "ContainerConfig": { + "type": "object", + "description": "Reusable container configuration shared across templates, pods, and serverless endpoints. Adding a field here automatically propagates to all three resources.\n", + "properties": { + "image": { + "type": "string", + "description": "Docker image reference", + "example": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1" + }, + "args": { + "type": "string", + "description": "Arguments passed to the container entrypoint", + "example": "" + }, + "disk": { + "type": "integer", + "minimum": 1, + "description": "Container disk in GB (ephemeral, wiped on restart)", + "example": 50 + }, + "ports": { + "type": "array", + "description": "Exposed ports, formatted as port/protocol", + "items": { + "type": "string" + }, + "example": [ + "8888/http", + "22/tcp" + ] + }, + "env": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "Environment variables as key-value pairs", + "example": { + "JUPYTER_PASSWORD": "hunter2" + } + }, + "registry": { + "type": "string", + "nullable": true, + "description": "Container registry credential ID (for private images)", + "example": null + } + } + }, + "Mounts": { + "type": "object", + "additionalProperties": false, + "description": "Storage mounts attached to a pod. At-most-one of `persistent` or\n`network` may be set today (mutually exclusive, enforced at the\nhandler with 400 if both are present). The `network` field is an\narray for forward compatibility with eventual multi-network-volume\nsupport, but `maxItems` is 1 today.\n\nPATCH semantics:\n- Omitting `mounts` or sending `{}` leaves the existing mount\n unchanged.\n- An explicit `network: []` is rejected with 400 (clearing mounts\n is not supported).\n- Mount kind is fixed at create — a PATCH that introduces a kind\n not present at create (persistent on a network pod, network on\n a persistent pod, or any mount on a previously-mountless pod)\n is rejected with 400.\n- The `volumeId` of a network mount is immutable; a PATCH that\n names a different `volumeId` is rejected with 400.\n- Partial mounts are not supported — every mount entry must\n include the full schema (`size` + `path` for persistent,\n `volumeId` + `path` for network). Missing required fields → 422.\n", + "properties": { + "persistent": { + "$ref": "#/components/schemas/PersistentMount" + }, + "network": { + "type": "array", + "maxItems": 1, + "items": { + "$ref": "#/components/schemas/NetworkMount" + } + } + } + }, + "TemplateMounts": { + "type": "object", + "additionalProperties": false, + "description": "Storage mounts attached to a template. Templates support only a\nsingle persistent mount today; any `network` property is rejected\nwith 422 by the schema validator.\n\nPATCH semantics: omitting `mounts` or sending `{}` leaves the\nexisting mount unchanged.\n", + "properties": { + "persistent": { + "$ref": "#/components/schemas/PersistentMount" + } + } + }, + "PersistentMount": { + "type": "object", + "required": [ + "size", + "path" + ], + "additionalProperties": false, + "description": "Host-local persistent storage. Pinned to the pod's host machine — data\ndoes not survive a host failure. Disallowed on CPU pods. Mutually\nexclusive with NetworkMount. Deprecated: prefer NetworkMount for any\ndata you cannot recreate.\n", + "properties": { + "size": { + "type": "integer", + "minimum": 10, + "description": "Host-local persistent storage in GB. Upstream enforces a 10 GB floor.", + "example": 20 + }, + "path": { + "type": "string", + "description": "Mount path inside the container. May be changed via PATCH.", + "example": "/workspace" + } + } + }, + "NetworkMount": { + "type": "object", + "required": [ + "volumeId", + "path" + ], + "additionalProperties": false, + "description": "Reference to a NetworkVolume. Custom paths are honored at runtime on\nboth GPU and CPU pods. The underlying `volumeId` is immutable\npost-create; the mount `path` may be changed via PATCH.\n", + "properties": { + "volumeId": { + "type": "string", + "description": "ID of an existing NetworkVolume in the same data center as the pod.", + "example": "vol_xyz" + }, + "path": { + "type": "string", + "description": "Mount path inside the container. No default — must be specified explicitly.", + "example": "/runpod-volume" + } + } + }, + "GpuConfig": { + "type": "object", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "string", + "description": "GPU type identifier", + "example": "NVIDIA GeForce RTX 4090" + }, + "count": { + "type": "integer", + "minimum": 1, + "default": 1, + "description": "Number of GPUs", + "example": 1 + } + } + }, + "BaseCpuConfig": { + "type": "object", + "required": [ + "id", + "vcpuCount" + ], + "properties": { + "id": { + "type": "string", + "description": "CPU flavor identifier, as returned by GET /v2/catalog/cpus.", + "example": "cpu5c", + "minLength": 1 + }, + "vcpuCount": { + "type": "integer", + "minimum": 2, + "description": "Number of vCPUs. Must be valid for the selected CPU flavor and must be a power of two.", + "example": 4 + } + } + }, + "CreateCpuConfig": { + "allOf": [ + { + "$ref": "#/components/schemas/BaseCpuConfig" + } + ] + }, + "CpuConfig": { + "allOf": [ + { + "$ref": "#/components/schemas/BaseCpuConfig" + }, + { + "type": "object", + "required": [ + "memory" + ], + "properties": { + "memory": { + "type": "integer", + "minimum": 1, + "description": "Memory allocated to the pod in GB.", + "example": 16 + } + } + } + ] + }, + "ScalerType": { + "type": "string", + "description": "Autoscaling strategy.\n- `QUEUE_DELAY` — scale on seconds a request waits in queue\n- `REQUEST_COUNT` — scale on in-flight request count\n", + "enum": [ + "QUEUE_DELAY", + "REQUEST_COUNT" + ] + }, + "FlashBoot": { + "type": "string", + "description": "FlashBoot cold-start acceleration mode.\n- `OFF` — disabled\n- `FLASHBOOT` — enabled\n- `PRIORITY_FLASHBOOT` — enabled with priority capacity\n", + "enum": [ + "OFF", + "FLASHBOOT", + "PRIORITY_FLASHBOOT" + ] + }, + "EndpointGpuConfig": { + "type": "object", + "required": [ + "pools" + ], + "properties": { + "pools": { + "type": "array", + "minItems": 1, + "description": "Serverless GPU pool IDs (as returned by `GET /v2/catalog/gpus` in\n`pool`). Workers are placed on whichever listed pool has capacity.\n", + "items": { + "type": "string" + }, + "example": [ + "ADA_24" + ] + }, + "count": { + "type": "integer", + "minimum": 1, + "default": 1, + "description": "GPUs per worker", + "example": 1 + } + } + }, + "Endpoint": { + "allOf": [ + { + "$ref": "#/components/schemas/ContainerConfig" + }, + { + "type": "object", + "required": [ + "id", + "name", + "workers", + "scaling", + "dataCenterIds", + "networkVolumes", + "timeout", + "flashboot", + "createdAt" + ], + "properties": { + "id": { + "type": "string", + "example": "ep_abc123" + }, + "name": { + "type": "string", + "example": "my-inference" + }, + "gpu": { + "nullable": true, + "allOf": [ + { + "$ref": "#/components/schemas/EndpointGpuConfig" + } + ] + }, + "cpu": { + "nullable": true, + "description": "Read-only. Present for CPU serverless endpoints; CPU create/update is not yet supported.", + "allOf": [ + { + "$ref": "#/components/schemas/CpuConfig" + } + ] + }, + "workers": { + "type": "object", + "required": [ + "min", + "max" + ], + "properties": { + "min": { + "type": "integer", + "minimum": 0, + "example": 0 + }, + "max": { + "type": "integer", + "minimum": 0, + "example": 5 + } + } + }, + "scaling": { + "type": "object", + "required": [ + "type", + "value", + "idleTimeout" + ], + "properties": { + "type": { + "$ref": "#/components/schemas/ScalerType" + }, + "value": { + "type": "integer", + "minimum": 1, + "example": 4 + }, + "idleTimeout": { + "type": "integer", + "minimum": 0, + "description": "Seconds before idle workers scale down", + "example": 5 + } + } + }, + "dataCenterIds": { + "type": "array", + "items": { + "type": "string" + }, + "example": [ + "US-TX-3" + ] + }, + "networkVolumes": { + "type": "array", + "items": { + "type": "string" + }, + "example": [ + "vol_abc" + ] + }, + "timeout": { + "type": "integer", + "description": "Per-request execution timeout in milliseconds", + "example": 300000 + }, + "flashboot": { + "$ref": "#/components/schemas/FlashBoot" + }, + "createdAt": { + "type": "string", + "format": "date-time", + "example": "2026-03-13T20:00:00Z" + } + } + } + ] + }, + "ListEndpointsResponse": { + "type": "object", + "required": [ + "endpoints" + ], + "properties": { + "endpoints": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Endpoint" + } + } + } + }, + "WorkerStatus": { + "type": "string", + "description": "Derived worker state, reconciled from the worker pod's lifecycle status\nand the live job-queue view.\n- `RUNNING` — actively processing a job\n- `IDLE` — ready and polling for jobs\n- `INITIALIZING` — starting up, not yet ready\n- `THROTTLED` — waiting on compute capacity\n- `UNHEALTHY` — failing health checks\n", + "x-enum-varnames": [ + "WorkerStatusRunning", + "WorkerStatusIdle", + "WorkerStatusInitializing", + "WorkerStatusThrottled", + "WorkerStatusUnhealthy" + ], + "enum": [ + "RUNNING", + "IDLE", + "INITIALIZING", + "THROTTLED", + "UNHEALTHY" + ] + }, + "Worker": { + "type": "object", + "required": [ + "id", + "status", + "gpuCount", + "isStale" + ], + "properties": { + "id": { + "type": "string", + "example": "worker_abc" + }, + "status": { + "$ref": "#/components/schemas/WorkerStatus" + }, + "isStale": { + "type": "boolean", + "description": "True when the worker is running an older endpoint configuration than\nthe current one (e.g. mid rolling-update). This is the authoritative\nflag: it is derived from `version` vs the response's `endpointVersion`,\nexcept on legacy endpoints (`endpointVersion` 1) where it falls back\nto a container-image comparison.\n", + "example": false + }, + "version": { + "type": "integer", + "nullable": true, + "description": "Endpoint configuration version this worker is running. Compare with\nthe response's `endpointVersion`. Null if unknown.\n", + "example": 4 + }, + "gpuCount": { + "type": "integer", + "minimum": 0, + "description": "GPUs allocated to the worker.", + "example": 1 + }, + "image": { + "type": "string", + "nullable": true, + "description": "Container image the worker is running.", + "example": "my-org/sdxl-worker:latest" + }, + "uptimeSeconds": { + "type": "integer", + "minimum": 0, + "nullable": true, + "description": "Seconds the worker has been running. Null until the worker is placed and running.", + "example": 3600 + }, + "gpuTypeId": { + "type": "string", + "nullable": true, + "description": "GPU type the worker is placed on. Null until the worker is placed.", + "example": "NVIDIA RTX 4090" + }, + "dataCenterId": { + "type": "string", + "nullable": true, + "description": "Data center the worker is placed in. Null until the worker is placed.", + "example": "US-TX-3" + }, + "startedAt": { + "type": "string", + "format": "date-time", + "nullable": true, + "description": "When the worker last started. Null if it has not started.", + "example": "2026-03-26T00:00:00Z" + } + } + }, + "WorkerSummary": { + "type": "object", + "description": "Histogram of the returned workers by status. The per-status counts are a\nroll-up of the `workers` array, so `running + idle + initializing +\nthrottled + unhealthy == total == len(workers)`.\n", + "required": [ + "running", + "idle", + "initializing", + "throttled", + "unhealthy", + "total" + ], + "properties": { + "running": { + "type": "integer", + "minimum": 0, + "description": "Workers actively processing a job.", + "example": 2 + }, + "idle": { + "type": "integer", + "minimum": 0, + "description": "Ready workers polling for jobs.", + "example": 1 + }, + "initializing": { + "type": "integer", + "minimum": 0, + "description": "Workers starting up, not yet ready.", + "example": 0 + }, + "throttled": { + "type": "integer", + "minimum": 0, + "description": "Workers waiting on compute capacity.", + "example": 0 + }, + "unhealthy": { + "type": "integer", + "minimum": 0, + "description": "Workers failing health checks.", + "example": 0 + }, + "total": { + "type": "integer", + "minimum": 0, + "description": "All workers currently allocated to the endpoint.", + "example": 3 + } + } + }, + "ListEndpointWorkersResponse": { + "type": "object", + "required": [ + "workers", + "summary" + ], + "properties": { + "workers": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Worker" + } + }, + "summary": { + "$ref": "#/components/schemas/WorkerSummary" + }, + "endpointVersion": { + "type": "integer", + "nullable": true, + "description": "The endpoint's current configuration version. A worker whose\n`version` differs is running stale config (see `worker.isStale`).\nNull if unknown.\n", + "example": 4 + } + } + }, + "CreateEndpointRequest": { + "allOf": [ + { + "$ref": "#/components/schemas/ContainerConfig" + }, + { + "type": "object", + "required": [ + "name", + "image", + "gpu" + ], + "properties": { + "name": { + "type": "string", + "minLength": 1, + "example": "my-inference" + }, + "gpu": { + "$ref": "#/components/schemas/EndpointGpuConfig" + }, + "workers": { + "type": "object", + "properties": { + "min": { + "type": "integer", + "minimum": 0, + "default": 0 + }, + "max": { + "type": "integer", + "minimum": 0, + "default": 3 + } + } + }, + "scaling": { + "type": "object", + "properties": { + "type": { + "$ref": "#/components/schemas/ScalerType" + }, + "value": { + "type": "integer", + "minimum": 1, + "default": 4 + }, + "idleTimeout": { + "type": "integer", + "minimum": 0, + "default": 5 + } + } + }, + "dataCenterIds": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Preferred data centers for placement. Omit or pass an empty array to let the scheduler choose." + }, + "networkVolumes": { + "type": "array", + "items": { + "type": "string" + } + }, + "timeout": { + "type": "integer", + "default": 300000 + }, + "flashboot": { + "allOf": [ + { + "$ref": "#/components/schemas/FlashBoot" + } + ], + "default": "OFF" + } + } + } + ] + }, + "UpdateEndpointRequest": { + "allOf": [ + { + "$ref": "#/components/schemas/ContainerConfig" + }, + { + "type": "object", + "description": "Only provided fields are changed.", + "properties": { + "name": { + "type": "string", + "minLength": 1 + }, + "gpu": { + "$ref": "#/components/schemas/EndpointGpuConfig" + }, + "workers": { + "type": "object", + "properties": { + "min": { + "type": "integer", + "minimum": 0 + }, + "max": { + "type": "integer", + "minimum": 0 + } + } + }, + "scaling": { + "type": "object", + "properties": { + "type": { + "$ref": "#/components/schemas/ScalerType" + }, + "value": { + "type": "integer", + "minimum": 1 + }, + "idleTimeout": { + "type": "integer", + "minimum": 0 + } + } + }, + "dataCenterIds": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Preferred data centers for placement. Omit or pass an empty array to let the scheduler choose." + }, + "networkVolumes": { + "type": "array", + "items": { + "type": "string" + } + }, + "timeout": { + "type": "integer" + }, + "flashboot": { + "$ref": "#/components/schemas/FlashBoot" + } + } + } + ] + }, + "Utilization": { + "type": "object", + "description": "Single-value utilization percentage (0–100). Shared by `cpu` and `memory`.", + "properties": { + "util": { + "type": "integer", + "example": 45 + } + } + }, + "PodGpuUtilization": { + "type": "object", + "description": "Per-GPU utilization metrics.", + "properties": { + "util": { + "type": "integer", + "example": 94 + }, + "memoryUtil": { + "type": "integer", + "example": 78 + } + } + }, + "PodRuntimePort": { + "type": "object", + "description": "Live port mapping for a running pod.", + "properties": { + "private": { + "type": "integer", + "example": 8888 + }, + "public": { + "type": "integer", + "nullable": true, + "example": 43210 + }, + "type": { + "type": "string", + "example": "http" + }, + "ip": { + "type": "string", + "nullable": true, + "example": "45.23.12.1" + } + } + }, + "PodRuntime": { + "type": "object", + "description": "Live utilization metrics for a running pod.", + "properties": { + "uptime": { + "type": "integer", + "description": "Seconds since the container started", + "example": 3600 + }, + "gpus": { + "type": "array", + "items": { + "$ref": "#/components/schemas/PodGpuUtilization" + } + }, + "cpu": { + "$ref": "#/components/schemas/Utilization" + }, + "memory": { + "$ref": "#/components/schemas/Utilization" + }, + "ports": { + "type": "array", + "items": { + "$ref": "#/components/schemas/PodRuntimePort" + } + } + } + }, + "PodStatus": { + "type": "string", + "description": "Lifecycle status of a pod.\n- `PROVISIONING` — pod is being allocated\n- `STARTING` — container is starting\n- `RUNNING` — container is healthy\n- `EXITED` — container exited (stopped)\n- `ERROR` — container is in an unrecoverable error state\n- `TERMINATED` — pod has been permanently deleted\n", + "enum": [ + "PROVISIONING", + "STARTING", + "RUNNING", + "EXITED", + "ERROR", + "TERMINATED" + ] + }, + "PodAction": { + "type": "string", + "description": "State transition to trigger on a pod.", + "enum": [ + "start", + "stop", + "restart", + "terminate" + ] + }, + "Cloud": { + "type": "string", + "description": "Cloud tier.\n- `SECURE` — RunPod-owned datacenter hardware\n- `COMMUNITY` — community-hosted hardware\n- `ALL` — eligible for either tier (request-only; responses always\n report the concrete tier the pod was placed on)\n", + "enum": [ + "SECURE", + "COMMUNITY", + "ALL" + ] + }, + "TemplateCategory": { + "type": "string", + "description": "Hardware family this template targets.\n- `CPU` — CPU-only workloads\n- `NVIDIA` — NVIDIA GPU workloads\n- `AMD` — AMD GPU workloads\n", + "enum": [ + "CPU", + "NVIDIA", + "AMD" + ] + }, + "PodGlobalNetworking": { + "type": "object", + "required": [ + "enabled" + ], + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether global networking is enabled, giving the pod a private IP reachable across data centers. Derived from whether the pod has an assigned global-network address.", + "example": true + }, + "ip": { + "type": "string", + "description": "The pod's assigned global-networking IP. Present only when enabled.", + "example": "10.65.1.42" + }, + "internalDns": { + "type": "string", + "description": "Internal DNS name (`.runpod.internal`), reachable from other globally-networked pods in the same account. Present only when enabled.", + "example": "gfj8b292vyg08g.runpod.internal" + } + } + }, + "Pod": { + "allOf": [ + { + "$ref": "#/components/schemas/ContainerConfig" + }, + { + "type": "object", + "required": [ + "id", + "name", + "status", + "actions", + "image", + "args", + "disk", + "mounts", + "ports", + "env", + "registry", + "cloud", + "dataCenterId", + "template", + "cost", + "locked", + "tags", + "runtime", + "createdAt", + "startedAt", + "globalNetworking" + ], + "properties": { + "id": { + "type": "string", + "example": "pod_abc123" + }, + "name": { + "type": "string", + "example": "my-training-pod" + }, + "status": { + "$ref": "#/components/schemas/PodStatus" + }, + "actions": { + "type": "array", + "description": "Valid state transitions for the current status.", + "items": { + "$ref": "#/components/schemas/PodAction" + } + }, + "mounts": { + "$ref": "#/components/schemas/Mounts" + }, + "gpu": { + "description": "Present for GPU pods; omitted from CPU pods.", + "allOf": [ + { + "$ref": "#/components/schemas/GpuConfig" + } + ] + }, + "cpu": { + "description": "Present for CPU pods; omitted from GPU pods.", + "allOf": [ + { + "$ref": "#/components/schemas/CpuConfig" + } + ] + }, + "cloud": { + "$ref": "#/components/schemas/Cloud" + }, + "dataCenterId": { + "type": "string", + "nullable": true, + "description": "Data center where the pod is running (assigned by scheduler)", + "example": "US-TX-3" + }, + "template": { + "type": "string", + "nullable": true, + "description": "ID of the template this pod was created from", + "example": null + }, + "cost": { + "type": "number", + "format": "float", + "description": "Current cost in USD per hour (0.0 when EXITED or TERMINATED)", + "example": 0.35 + }, + "locked": { + "type": "boolean", + "description": "Whether the pod is locked (prevents stopping or resetting)", + "example": false + }, + "globalNetworking": { + "$ref": "#/components/schemas/PodGlobalNetworking" + }, + "tags": { + "type": "array", + "description": "Tags attached to this pod.", + "items": { + "$ref": "#/components/schemas/Tag" + } + }, + "runtime": { + "nullable": true, + "description": "Live utilization metrics. Null when the pod is not RUNNING.", + "allOf": [ + { + "$ref": "#/components/schemas/PodRuntime" + } + ] + }, + "createdAt": { + "type": "string", + "format": "date-time", + "example": "2026-03-13T20:00:00Z" + }, + "startedAt": { + "type": "string", + "format": "date-time", + "nullable": true, + "example": "2026-03-13T20:00:00Z" + } + } + } + ] + }, + "CreatePodRequest": { + "allOf": [ + { + "$ref": "#/components/schemas/ContainerConfig" + }, + { + "type": "object", + "required": [ + "name", + "image" + ], + "description": "Request body for creating a pod. Exactly one of `gpu` or `cpu`\nmust be set — enforced at the handler layer. For CPU pods, memory\nis derived by the API from the selected flavor's RAM multiplier;\nclients provide only CPU flavor and vCPU count. CPU pods support\ncontainer disk and network volumes only; `mounts.persistent` is\ninvalid when `cpu` is set.\n", + "properties": { + "name": { + "type": "string", + "minLength": 1, + "example": "my-training-pod" + }, + "mounts": { + "$ref": "#/components/schemas/Mounts" + }, + "gpu": { + "$ref": "#/components/schemas/GpuConfig" + }, + "cpu": { + "$ref": "#/components/schemas/CreateCpuConfig" + }, + "cloud": { + "$ref": "#/components/schemas/Cloud" + }, + "dataCenterIds": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Preferred data centers for placement. Omit or pass an empty\narray to let the scheduler choose.\n", + "example": [ + "US-TX-3" + ] + }, + "globalNetworking": { + "type": "boolean", + "default": false, + "description": "Enable global networking, giving the pod a private IP reachable across data centers. Requires an NVIDIA GPU and a global-networking-enabled data center (both enforced upstream). See `GET /v2/catalog/datacenters` (`globalNetwork`) for eligible data centers.", + "example": false + } + } + } + ] + }, + "UpdatePodRequest": { + "allOf": [ + { + "$ref": "#/components/schemas/ContainerConfig" + }, + { + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 1 + }, + "mounts": { + "$ref": "#/components/schemas/Mounts" + }, + "locked": { + "type": "boolean", + "description": "Lock the pod (true) or unlock it (false). Locked pods cannot be stopped or reset." + }, + "globalNetworking": { + "type": "boolean", + "description": "Enable (true) or disable (false) global networking. Takes effect on the next pod start/restart, not live. Requires an NVIDIA GPU and a global-networking-enabled data center (both enforced upstream). See `GET /v2/catalog/datacenters` (`globalNetwork`) for eligible data centers." + } + } + } + ] + }, + "PodActionRequest": { + "type": "object", + "required": [ + "action" + ], + "properties": { + "action": { + "$ref": "#/components/schemas/PodAction" + } + } + }, + "ListPodsResponse": { + "type": "object", + "required": [ + "pods" + ], + "properties": { + "pods": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Pod" + } + } + } + }, + "Template": { + "allOf": [ + { + "$ref": "#/components/schemas/ContainerConfig" + }, + { + "type": "object", + "required": [ + "id", + "name", + "image", + "args", + "disk", + "mounts", + "ports", + "env", + "registry", + "serverless", + "public", + "category" + ], + "properties": { + "id": { + "type": "string", + "example": "tpl_abc" + }, + "name": { + "type": "string", + "example": "My PyTorch Template" + }, + "mounts": { + "$ref": "#/components/schemas/TemplateMounts" + }, + "serverless": { + "type": "boolean", + "description": "Whether this template is for serverless workers (true) or pods (false)", + "example": false + }, + "public": { + "type": "boolean", + "description": "Whether this template is visible to other RunPod users", + "example": false + }, + "category": { + "$ref": "#/components/schemas/TemplateCategory" + } + } + } + ] + }, + "CreateTemplateRequest": { + "allOf": [ + { + "$ref": "#/components/schemas/ContainerConfig" + }, + { + "type": "object", + "required": [ + "name", + "image", + "category" + ], + "properties": { + "name": { + "type": "string", + "minLength": 1, + "example": "My PyTorch Template" + }, + "mounts": { + "$ref": "#/components/schemas/TemplateMounts" + }, + "serverless": { + "type": "boolean", + "default": false + }, + "public": { + "type": "boolean", + "default": false + }, + "category": { + "$ref": "#/components/schemas/TemplateCategory" + } + } + } + ] + }, + "UpdateTemplateRequest": { + "allOf": [ + { + "$ref": "#/components/schemas/ContainerConfig" + }, + { + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 1 + }, + "mounts": { + "$ref": "#/components/schemas/TemplateMounts" + }, + "serverless": { + "type": "boolean" + }, + "public": { + "type": "boolean" + }, + "category": { + "$ref": "#/components/schemas/TemplateCategory" + } + } + } + ] + }, + "ListTemplatesResponse": { + "type": "object", + "required": [ + "templates" + ], + "properties": { + "templates": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Template" + } + } + } + }, + "TagResourceType": { + "type": "string", + "description": "Resource type attached to a tag.", + "enum": [ + "POD", + "NETWORK_VOLUME", + "CLUSTER", + "SERVERLESS_ENDPOINT" + ], + "example": "POD" + }, + "TaggedResource": { + "type": "object", + "required": [ + "id", + "type" + ], + "additionalProperties": false, + "properties": { + "id": { + "type": "string", + "description": "Resource identifier.", + "example": "pod_abc123" + }, + "type": { + "$ref": "#/components/schemas/TagResourceType" + } + } + }, + "Tag": { + "type": "object", + "required": [ + "id", + "key", + "value" + ], + "additionalProperties": false, + "properties": { + "id": { + "type": "string", + "description": "Tag identifier", + "example": "tag_abc123" + }, + "key": { + "type": "string", + "minLength": 1, + "description": "Tag key", + "example": "project" + }, + "value": { + "type": "string", + "minLength": 1, + "description": "Tag value", + "example": "gpt-training" + }, + "resources": { + "type": "array", + "description": "Populated only on direct tag responses when `?include=resources` is provided; omitted when the tag appears nested in another resource or if no resources have the tag.", + "items": { + "$ref": "#/components/schemas/TaggedResource" + } + } + } + }, + "CreateTagRequest": { + "type": "object", + "required": [ + "key", + "value" + ], + "additionalProperties": false, + "properties": { + "key": { + "type": "string", + "minLength": 1, + "example": "project" + }, + "value": { + "type": "string", + "minLength": 1, + "example": "gpt-training" + }, + "resources": { + "type": "array", + "description": "Resources to attach to the tag at create time. If any resource cannot be attached, tag creation returns an error rather than silently dropping the association.", + "items": { + "$ref": "#/components/schemas/TaggedResource" + } + } + } + }, + "UpdateTagRequest": { + "type": "object", + "minProperties": 1, + "additionalProperties": false, + "description": "At least one of `key`, `value`, or `resources` must be provided.", + "properties": { + "key": { + "type": "string", + "minLength": 1, + "example": "project" + }, + "value": { + "type": "string", + "minLength": 1, + "example": "gpt-training" + }, + "resources": { + "type": "array", + "description": "Replaces resource associations when present. Omit `resources` to leave\nexisting associations unchanged. Send `resources: []` to remove all\nassociations. Send a non-empty array to replace current associations with\nexactly those resources.\n", + "items": { + "$ref": "#/components/schemas/TaggedResource" + } + } + } + }, + "ListTagsResponse": { + "type": "object", + "required": [ + "tags" + ], + "additionalProperties": false, + "properties": { + "tags": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Tag" + } + } + } + }, + "NetworkVolume": { + "type": "object", + "required": [ + "id", + "name", + "size", + "dataCenter", + "tags" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique network volume identifier", + "example": "agv6w2qcg7" + }, + "name": { + "type": "string", + "description": "Human-readable name (not required to be unique)", + "example": "my-dataset" + }, + "size": { + "type": "integer", + "minimum": 1, + "maximum": 4000, + "description": "Allocated storage in GB", + "example": 50 + }, + "dataCenter": { + "type": "string", + "description": "Data center location; immutable after creation", + "example": "EU-RO-1" + }, + "tags": { + "type": "array", + "description": "Tags attached to this network volume.", + "items": { + "$ref": "#/components/schemas/Tag" + } + } + } + }, + "CreateNetworkVolumeRequest": { + "type": "object", + "required": [ + "name", + "size", + "dataCenter" + ], + "properties": { + "name": { + "type": "string", + "minLength": 1, + "description": "Human-readable name", + "example": "my-dataset" + }, + "size": { + "type": "integer", + "minimum": 1, + "maximum": 4000, + "description": "Storage to allocate in GB", + "example": 50 + }, + "dataCenter": { + "type": "string", + "minLength": 1, + "description": "Data center in which to create the volume", + "example": "EU-RO-1" + } + } + }, + "UpdateNetworkVolumeRequest": { + "type": "object", + "description": "All fields are optional. Only provided fields are updated.", + "properties": { + "name": { + "type": "string", + "minLength": 1, + "description": "New human-readable name", + "example": "renamed-volume" + }, + "size": { + "type": "integer", + "minimum": 1, + "maximum": 4000, + "description": "New size in GB. Must be greater than or equal to the current size —\nnetwork volume storage cannot be reduced.\n", + "example": 100 + } + } + }, + "ListNetworkVolumesResponse": { + "type": "object", + "required": [ + "networkVolumes" + ], + "properties": { + "networkVolumes": { + "type": "array", + "items": { + "$ref": "#/components/schemas/NetworkVolume" + } + } + } + }, + "Registry": { + "type": "object", + "required": [ + "id", + "name" + ], + "properties": { + "id": { + "type": "string", + "example": "reg_abc" + }, + "name": { + "type": "string", + "example": "my-private-registry" + } + } + }, + "CreateRegistryRequest": { + "type": "object", + "required": [ + "name", + "username", + "password" + ], + "properties": { + "name": { + "type": "string", + "minLength": 1, + "example": "my-private-registry" + }, + "username": { + "type": "string", + "minLength": 1, + "description": "Registry username (write-only, not returned in responses)" + }, + "password": { + "type": "string", + "minLength": 1, + "description": "Registry password (write-only, not returned in responses)" + } + } + }, + "ListRegistriesResponse": { + "type": "object", + "required": [ + "registries" + ], + "properties": { + "registries": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Registry" + } + } + } + }, + "GpuType": { + "type": "object", + "required": [ + "id", + "name", + "pool", + "manufacturer", + "memory", + "secure", + "community", + "price", + "maxCount" + ], + "properties": { + "id": { + "type": "string", + "description": "Individual GPU type identifier (use for pod creation)", + "example": "NVIDIA GeForce RTX 4090" + }, + "name": { + "type": "string", + "example": "RTX 4090" + }, + "pool": { + "type": "string", + "nullable": true, + "description": "Serverless GPU pool ID (use for serverless endpoint creation). Null if GPU is not in a serverless pool.", + "example": "ADA_24" + }, + "manufacturer": { + "type": "string", + "example": "NVIDIA" + }, + "memory": { + "type": "integer", + "description": "VRAM in GB", + "example": 24 + }, + "secure": { + "type": "boolean", + "description": "Available on secure cloud", + "example": true + }, + "community": { + "type": "boolean", + "description": "Available on community cloud", + "example": true + }, + "price": { + "type": "object", + "required": [ + "secure", + "community" + ], + "properties": { + "secure": { + "type": "number", + "format": "float", + "example": 0.44 + }, + "community": { + "type": "number", + "format": "float", + "example": 0.31 + } + } + }, + "maxCount": { + "type": "object", + "required": [ + "secure", + "community" + ], + "properties": { + "secure": { + "type": "integer", + "example": 8 + }, + "community": { + "type": "integer", + "example": 4 + } + } + }, + "availability": { + "description": "Overall GPU availability. Present only when requested with include=AVAILABILITY.", + "$ref": "#/components/schemas/AvailabilityLevel" + }, + "dataCenters": { + "type": "array", + "description": "Per-datacenter GPU availability. Present only when requested with include=AVAILABILITY.", + "items": { + "$ref": "#/components/schemas/DataCenterAvailability" + } + } + } + }, + "AvailabilityLevel": { + "type": "string", + "description": "Catalog stock availability level.", + "enum": [ + "NONE", + "LOW", + "MEDIUM", + "HIGH" + ] + }, + "Product": { + "type": "string", + "description": "Catalog product availability context.", + "enum": [ + "POD", + "CLUSTER", + "SERVERLESS" + ] + }, + "CpuProduct": { + "type": "string", + "description": "CPU catalog product availability context.", + "enum": [ + "POD", + "SERVERLESS" + ] + }, + "CatalogInclude": { + "type": "string", + "description": "Catalog include expansion. Only AVAILABILITY is supported today; additional include values may be added in the future.", + "enum": [ + "AVAILABILITY" + ] + }, + "DataCenterInclude": { + "type": "string", + "description": "Data center catalog availability expansion.", + "enum": [ + "GPU_AVAILABILITY", + "CPU_AVAILABILITY" + ] + }, + "GpuCloudFilter": { + "type": "string", + "description": "GPU availability cloud filter.", + "enum": [ + "SECURE", + "COMMUNITY" + ] + }, + "VolumeType": { + "type": "string", + "description": "Data center network volume storage type.", + "enum": [ + "STANDARD", + "HIGH_PERFORMANCE" + ] + }, + "CatalogResourceAvailability": { + "type": "object", + "required": [ + "id", + "name", + "availability" + ], + "properties": { + "id": { + "type": "string", + "description": "Catalog resource identifier.", + "example": "NVIDIA GeForce RTX 4090" + }, + "name": { + "type": "string", + "description": "Human-readable catalog resource name.", + "example": "RTX 4090" + }, + "availability": { + "$ref": "#/components/schemas/AvailabilityLevel" + } + } + }, + "DataCenterAvailability": { + "type": "object", + "required": [ + "id", + "name", + "availability" + ], + "properties": { + "id": { + "type": "string", + "description": "Data center identifier.", + "example": "US-CA-2" + }, + "name": { + "type": "string", + "description": "Human-readable data center name.", + "example": "US California 2" + }, + "availability": { + "$ref": "#/components/schemas/AvailabilityLevel" + } + } + }, + "ListGpuTypesResponse": { + "type": "object", + "required": [ + "gpus" + ], + "properties": { + "gpus": { + "type": "array", + "items": { + "$ref": "#/components/schemas/GpuType" + } + } + } + }, + "CpuType": { + "type": "object", + "required": [ + "id", + "name", + "group", + "vcpu", + "ramGbPerVcpu", + "price" + ], + "properties": { + "id": { + "type": "string", + "description": "CPU flavor identifier (use in cpu.id for pod creation)", + "example": "cpu5c" + }, + "name": { + "type": "string", + "description": "Human-readable flavor name", + "example": "Compute-Optimized" + }, + "group": { + "type": "string", + "description": "CPU generation group", + "example": "Gen 5" + }, + "vcpu": { + "type": "object", + "required": [ + "min", + "max" + ], + "properties": { + "min": { + "type": "integer", + "example": 2 + }, + "max": { + "type": "integer", + "example": 32 + } + } + }, + "ramGbPerVcpu": { + "type": "number", + "format": "float", + "description": "GB of RAM allocated per vCPU. Multiply by the chosen vCPU\ncount (within `vcpu.min`..`vcpu.max`) to get the total RAM\nfor an instance of this flavor. May be fractional.\n", + "example": 2.5 + }, + "price": { + "type": "object", + "required": [ + "securePerVcpu", + "serverlessPerVcpu" + ], + "properties": { + "securePerVcpu": { + "type": "number", + "format": "float", + "description": "Price for secure pods per vCPU. Multiply by the chosen vCPU\ncount (within `vcpu.min`..`vcpu.max`) to get the total price.\n", + "example": 0.04 + }, + "serverlessPerVcpu": { + "type": "number", + "format": "float", + "description": "Price for serverless per vCPU. Multiply by the chosen vCPU\ncount (within `vcpu.min`..`vcpu.max`) to get the total price.\n", + "example": 0.03 + } + } + }, + "availability": { + "description": "Overall CPU availability. Present only when requested with include=AVAILABILITY.", + "$ref": "#/components/schemas/AvailabilityLevel" + }, + "dataCenters": { + "type": "array", + "description": "Per-datacenter CPU availability. Present only when requested with include=AVAILABILITY.", + "items": { + "$ref": "#/components/schemas/DataCenterAvailability" + } + } + } + }, + "ListCpuTypesResponse": { + "type": "object", + "required": [ + "cpus" + ], + "properties": { + "cpus": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CpuType" + } + } + } + }, + "DataCenter": { + "type": "object", + "required": [ + "id", + "name", + "region", + "networkVolumeTypes", + "compliance", + "globalNetwork" + ], + "properties": { + "id": { + "type": "string", + "example": "US-TX-3" + }, + "name": { + "type": "string", + "example": "US Texas 3" + }, + "region": { + "$ref": "#/components/schemas/DataCenterRegion" + }, + "globalNetwork": { + "type": "boolean", + "description": "Whether this data center supports global networking (private cross-datacenter pod-to-pod network).", + "example": true + }, + "networkVolumeTypes": { + "type": "array", + "items": { + "$ref": "#/components/schemas/VolumeType" + }, + "description": "Network volume tiers this DC supports. Empty = none." + }, + "compliance": { + "type": "array", + "description": "Compliance certifications held by this data center", + "items": { + "$ref": "#/components/schemas/Compliance" + }, + "example": [ + "GDPR", + "ISO_IEC_27001", + "SOC_2_TYPE_2" + ] + }, + "gpuAvailability": { + "type": "array", + "description": "Per-GPU availability in this data center. Present only when requested with include=gpuAvailability.", + "items": { + "$ref": "#/components/schemas/CatalogResourceAvailability" + } + }, + "cpuAvailability": { + "type": "array", + "description": "Per-CPU availability in this data center. Present only when requested with include=cpuAvailability.", + "items": { + "$ref": "#/components/schemas/CatalogResourceAvailability" + } + } + } + }, + "DataCenterRegion": { + "type": "string", + "description": "Continental region containing the data center.", + "example": "EUROPE", + "enum": [ + "NORTH_AMERICA", + "SOUTH_AMERICA", + "EUROPE", + "ASIA", + "MIDDLE_EAST", + "AFRICA", + "OCEANIA", + "ANTARCTICA", + "UNKNOWN" + ] + }, + "Compliance": { + "type": "string", + "description": "Compliance certifications.", + "enum": [ + "GDPR", + "ISO_IEC_27001", + "ISO_14001", + "PCI_DSS", + "HITRUST", + "SOC_1_TYPE_2", + "SOC_2_TYPE_2", + "SOC_3_TYPE_2", + "ITAR", + "FISMA_HIGH", + "HIPAA", + "RENEWABLE" + ] + }, + "ListDataCentersResponse": { + "type": "object", + "required": [ + "dataCenters" + ], + "properties": { + "dataCenters": { + "type": "array", + "items": { + "$ref": "#/components/schemas/DataCenter" + } + } + } + }, + "BillingTimeRange": { + "type": "object", + "description": "Half-open time range [startTime, endTime) in RFC 3339. On a record it is the time bucket; on a query echo it is the resolved window.\n", + "required": [ + "startTime", + "endTime" + ], + "properties": { + "startTime": { + "type": "string", + "format": "date-time", + "description": "Start of the range, inclusive (RFC 3339).", + "example": "2026-06-01T00:00:00Z" + }, + "endTime": { + "type": "string", + "format": "date-time", + "description": "End of the range, exclusive (RFC 3339).", + "example": "2026-06-02T00:00:00Z" + } + } + }, + "BillingBucketSize": { + "type": "string", + "enum": [ + "hour", + "day", + "week", + "month", + "year" + ], + "x-enum-varnames": [ + "BillingBucketSizeHour", + "BillingBucketSizeDay", + "BillingBucketSizeWeek", + "BillingBucketSizeMonth", + "BillingBucketSizeYear" + ], + "default": "day", + "description": "Length of each billing time bucket.", + "example": "day" + }, + "BillingAmounts": { + "type": "object", + "description": "Total spend across all billable RunPod resources with each cost component broken out, fully prefixed by resource. Backs the aggregate record's amounts and the metadata totals.\n", + "required": [ + "totalAmount", + "podGpuAmount", + "podCpuAmount", + "podDiskAmount", + "serverlessGpuAmount", + "serverlessCpuAmount", + "serverlessDiskAmount", + "serverlessFeeAmount", + "storageStandardAmount", + "storageHighPerformanceAmount", + "endpointAmount", + "clusterGpuAmount", + "clusterDiskAmount", + "clusterNetworkingAmount" + ], + "properties": { + "totalAmount": { + "type": "number", + "format": "double", + "description": "Total cost in USD for the bucket across all resources.", + "example": 42.34 + }, + "podGpuAmount": { + "type": "number", + "format": "double", + "description": "GPU pod compute cost in USD for the bucket." + }, + "podCpuAmount": { + "type": "number", + "format": "double", + "description": "CPU pod compute cost in USD for the bucket." + }, + "podDiskAmount": { + "type": "number", + "format": "double", + "description": "Pod disk cost in USD for the bucket." + }, + "serverlessGpuAmount": { + "type": "number", + "format": "double", + "description": "Serverless GPU compute cost in USD for the bucket." + }, + "serverlessCpuAmount": { + "type": "number", + "format": "double", + "description": "Serverless CPU compute cost in USD for the bucket." + }, + "serverlessDiskAmount": { + "type": "number", + "format": "double", + "description": "Serverless disk cost in USD for the bucket." + }, + "serverlessFeeAmount": { + "type": "number", + "format": "double", + "description": "Serverless platform fee in USD for the bucket." + }, + "storageStandardAmount": { + "type": "number", + "format": "double", + "description": "Standard network volume storage cost in USD for the bucket." + }, + "storageHighPerformanceAmount": { + "type": "number", + "format": "double", + "description": "High-performance network volume storage cost in USD for the bucket." + }, + "endpointAmount": { + "type": "number", + "format": "double", + "description": "RunPod public endpoint cost in USD for the bucket." + }, + "clusterGpuAmount": { + "type": "number", + "format": "double", + "description": "Instant Cluster GPU compute cost in USD for the bucket." + }, + "clusterDiskAmount": { + "type": "number", + "format": "double", + "description": "Instant Cluster disk cost in USD for the bucket." + }, + "clusterNetworkingAmount": { + "type": "number", + "format": "double", + "description": "Instant Cluster inter-node networking cost in USD for the bucket." + } + } + }, + "BillingRecord": { + "description": "A single time-bucketed record of total spend across all billable RunPod resources, with each cost component broken out. Returned by GET /v2/billing.\n", + "allOf": [ + { + "$ref": "#/components/schemas/BillingTimeRange" + }, + { + "$ref": "#/components/schemas/BillingAmounts" + } + ] + }, + "PodBillingAmounts": { + "type": "object", + "description": "Pod cost components covering both GPU and CPU pods. Backs a record's amounts and the metadata totals.\n", + "required": [ + "totalAmount", + "gpuAmount", + "cpuAmount", + "diskAmount" + ], + "properties": { + "totalAmount": { + "type": "number", + "format": "double", + "description": "Total pod cost in USD for the bucket.", + "example": 12.34 + }, + "gpuAmount": { + "type": "number", + "format": "double", + "description": "GPU pod compute cost in USD for the bucket." + }, + "cpuAmount": { + "type": "number", + "format": "double", + "description": "CPU pod compute cost in USD for the bucket." + }, + "diskAmount": { + "type": "number", + "format": "double", + "description": "Pod disk cost in USD for the bucket." + } + } + }, + "PodBillingRecord": { + "description": "A single time-bucketed pod billing record, covering both GPU and CPU pods. Returned by GET /v2/billing/pods.\n", + "allOf": [ + { + "$ref": "#/components/schemas/BillingTimeRange" + }, + { + "$ref": "#/components/schemas/PodBillingAmounts" + }, + { + "type": "object", + "required": [ + "podId" + ], + "properties": { + "podId": { + "type": "string", + "description": "The pod this record bills. When the podId filter is set every record carries that id; otherwise one record is emitted per pod per bucket.\n", + "example": "pod_abc123" + } + } + } + ] + }, + "ServerlessBillingAmounts": { + "type": "object", + "description": "Serverless cost components. Backs a record's amounts and the metadata totals.\n", + "required": [ + "totalAmount", + "gpuAmount", + "cpuAmount", + "diskAmount", + "feeAmount" + ], + "properties": { + "totalAmount": { + "type": "number", + "format": "double", + "description": "Total serverless cost in USD for the bucket.", + "example": 8.9 + }, + "gpuAmount": { + "type": "number", + "format": "double", + "description": "Serverless GPU compute cost in USD for the bucket." + }, + "cpuAmount": { + "type": "number", + "format": "double", + "description": "Serverless CPU compute cost in USD for the bucket." + }, + "diskAmount": { + "type": "number", + "format": "double", + "description": "Serverless disk cost in USD for the bucket." + }, + "feeAmount": { + "type": "number", + "format": "double", + "description": "Serverless platform fee in USD for the bucket." + } + } + }, + "ServerlessBillingRecord": { + "description": "A single time-bucketed serverless billing record. Returned by GET /v2/billing/serverless.\n", + "allOf": [ + { + "$ref": "#/components/schemas/BillingTimeRange" + }, + { + "$ref": "#/components/schemas/ServerlessBillingAmounts" + }, + { + "type": "object", + "required": [ + "serverlessId" + ], + "properties": { + "serverlessId": { + "type": "string", + "description": "The serverless endpoint this record bills. When the serverlessId filter is set every record carries that id; otherwise one record is emitted per serverless endpoint per bucket.\n", + "example": "ep_abc123" + } + } + } + ] + }, + "EndpointBillingAmounts": { + "type": "object", + "description": "RunPod public endpoint cost. Backs a record's amounts and the metadata totals.\n", + "required": [ + "totalAmount" + ], + "properties": { + "totalAmount": { + "type": "number", + "format": "double", + "description": "Total public endpoint cost in USD for the bucket.", + "example": 3.21 + } + } + }, + "EndpointBillingRecord": { + "description": "A single time-bucketed RunPod public endpoint billing record. Returned by GET /v2/billing/endpoints.\n", + "allOf": [ + { + "$ref": "#/components/schemas/BillingTimeRange" + }, + { + "$ref": "#/components/schemas/EndpointBillingAmounts" + } + ] + }, + "NetworkVolumeBillingAmounts": { + "type": "object", + "description": "Network volume storage cost, split into standard and high-performance. Backs a record's amounts and the metadata totals.\n", + "required": [ + "totalAmount", + "standardAmount", + "highPerformanceAmount" + ], + "properties": { + "totalAmount": { + "type": "number", + "format": "double", + "description": "Total network volume cost in USD for the bucket, across standard and high-performance storage.\n", + "example": 5.79 + }, + "standardAmount": { + "type": "number", + "format": "double", + "description": "Standard storage cost in USD for the bucket." + }, + "highPerformanceAmount": { + "type": "number", + "format": "double", + "description": "High-performance storage cost in USD for the bucket." + } + } + }, + "NetworkVolumeBillingRecord": { + "description": "A single time-bucketed network volume billing record, split into standard and high-performance storage. Returned by GET /v2/billing/networkvolumes.\n", + "allOf": [ + { + "$ref": "#/components/schemas/BillingTimeRange" + }, + { + "$ref": "#/components/schemas/NetworkVolumeBillingAmounts" + }, + { + "type": "object", + "required": [ + "networkVolumeId" + ], + "properties": { + "networkVolumeId": { + "type": "string", + "description": "The network volume this record bills. When the networkVolumeId filter is set every record carries that id; otherwise one record is emitted per network volume per bucket.\n", + "example": "vol_abc123" + } + } + } + ] + }, + "ClusterBillingAmounts": { + "type": "object", + "description": "Instant Cluster cost components (GPU-only, no CPU). Backs a record's amounts and the metadata totals.\n", + "required": [ + "totalAmount", + "gpuAmount", + "diskAmount", + "networkingAmount" + ], + "properties": { + "totalAmount": { + "type": "number", + "format": "double", + "description": "Total Instant Cluster cost in USD for the bucket.", + "example": 99 + }, + "gpuAmount": { + "type": "number", + "format": "double", + "description": "Cluster GPU compute cost in USD for the bucket." + }, + "diskAmount": { + "type": "number", + "format": "double", + "description": "Cluster disk cost in USD for the bucket." + }, + "networkingAmount": { + "type": "number", + "format": "double", + "description": "Cluster inter-node networking cost in USD for the bucket." + } + } + }, + "ClusterBillingRecord": { + "description": "A single time-bucketed Instant Cluster billing record. Clusters are GPU-only (no CPU component). Returned by GET /v2/billing/clusters.\n", + "allOf": [ + { + "$ref": "#/components/schemas/BillingTimeRange" + }, + { + "$ref": "#/components/schemas/ClusterBillingAmounts" + }, + { + "type": "object", + "required": [ + "clusterId" + ], + "properties": { + "clusterId": { + "type": "string", + "description": "The Instant Cluster this record bills. When the clusterId filter is set every record carries that id; otherwise one record is emitted per cluster per bucket.\n", + "example": "cluster_abc123" + } + } + } + ] + }, + "BillingQuery": { + "description": "Resolved query window and granularity (routes without a filter).", + "allOf": [ + { + "$ref": "#/components/schemas/BillingTimeRange" + }, + { + "type": "object", + "required": [ + "bucketSize" + ], + "properties": { + "bucketSize": { + "$ref": "#/components/schemas/BillingBucketSize" + } + } + } + ] + }, + "PodBillingQuery": { + "allOf": [ + { + "$ref": "#/components/schemas/BillingQuery" + }, + { + "type": "object", + "properties": { + "podId": { + "type": "string", + "nullable": true, + "description": "The podId filter applied, if any." + } + } + } + ] + }, + "ServerlessBillingQuery": { + "allOf": [ + { + "$ref": "#/components/schemas/BillingQuery" + }, + { + "type": "object", + "properties": { + "serverlessId": { + "type": "string", + "nullable": true, + "description": "The serverlessId filter applied, if any." + } + } + } + ] + }, + "NetworkVolumeBillingQuery": { + "allOf": [ + { + "$ref": "#/components/schemas/BillingQuery" + }, + { + "type": "object", + "properties": { + "networkVolumeId": { + "type": "string", + "nullable": true, + "description": "The networkVolumeId filter applied, if any." + } + } + } + ] + }, + "ClusterBillingQuery": { + "allOf": [ + { + "$ref": "#/components/schemas/BillingQuery" + }, + { + "type": "object", + "properties": { + "clusterId": { + "type": "string", + "nullable": true, + "description": "The clusterId filter applied, if any." + } + } + } + ] + }, + "BillingMetadata": { + "type": "object", + "required": [ + "query", + "recordCount", + "totals" + ], + "properties": { + "query": { + "$ref": "#/components/schemas/BillingQuery" + }, + "recordCount": { + "type": "integer", + "description": "Number of records returned." + }, + "totals": { + "$ref": "#/components/schemas/BillingAmounts" + } + } + }, + "PodBillingMetadata": { + "type": "object", + "required": [ + "query", + "recordCount", + "uniquePodCount", + "totals" + ], + "properties": { + "query": { + "$ref": "#/components/schemas/PodBillingQuery" + }, + "recordCount": { + "type": "integer", + "description": "Number of records returned (buckets times distinct pods)." + }, + "uniquePodCount": { + "type": "integer", + "description": "Number of distinct pods the records span." + }, + "totals": { + "$ref": "#/components/schemas/PodBillingAmounts" + } + } + }, + "ServerlessBillingMetadata": { + "type": "object", + "required": [ + "query", + "recordCount", + "uniqueServerlessCount", + "totals" + ], + "properties": { + "query": { + "$ref": "#/components/schemas/ServerlessBillingQuery" + }, + "recordCount": { + "type": "integer", + "description": "Number of records returned (buckets times distinct endpoints)." + }, + "uniqueServerlessCount": { + "type": "integer", + "description": "Number of distinct serverless endpoints the records span." + }, + "totals": { + "$ref": "#/components/schemas/ServerlessBillingAmounts" + } + } + }, + "EndpointBillingMetadata": { + "type": "object", + "required": [ + "query", + "recordCount", + "totals" + ], + "properties": { + "query": { + "$ref": "#/components/schemas/BillingQuery" + }, + "recordCount": { + "type": "integer" + }, + "totals": { + "$ref": "#/components/schemas/EndpointBillingAmounts" + } + } + }, + "NetworkVolumeBillingMetadata": { + "type": "object", + "required": [ + "query", + "recordCount", + "uniqueNetworkVolumeCount", + "totals" + ], + "properties": { + "query": { + "$ref": "#/components/schemas/NetworkVolumeBillingQuery" + }, + "recordCount": { + "type": "integer", + "description": "Number of records returned (buckets times distinct volumes)." + }, + "uniqueNetworkVolumeCount": { + "type": "integer", + "description": "Number of distinct network volumes the records span." + }, + "totals": { + "$ref": "#/components/schemas/NetworkVolumeBillingAmounts" + } + } + }, + "ClusterBillingMetadata": { + "type": "object", + "required": [ + "query", + "recordCount", + "uniqueClusterCount", + "totals" + ], + "properties": { + "query": { + "$ref": "#/components/schemas/ClusterBillingQuery" + }, + "recordCount": { + "type": "integer", + "description": "Number of records returned (buckets times distinct clusters)." + }, + "uniqueClusterCount": { + "type": "integer", + "description": "Number of distinct clusters the records span." + }, + "totals": { + "$ref": "#/components/schemas/ClusterBillingAmounts" + } + } + }, + "ListBillingResponse": { + "type": "object", + "description": "Aggregated billing records across all RunPod resources.", + "required": [ + "records", + "metadata" + ], + "properties": { + "records": { + "type": "array", + "items": { + "$ref": "#/components/schemas/BillingRecord" + } + }, + "metadata": { + "$ref": "#/components/schemas/BillingMetadata" + } + } + }, + "ListPodBillingResponse": { + "type": "object", + "description": "Billing records for pods.", + "required": [ + "records", + "metadata" + ], + "properties": { + "records": { + "type": "array", + "items": { + "$ref": "#/components/schemas/PodBillingRecord" + } + }, + "metadata": { + "$ref": "#/components/schemas/PodBillingMetadata" + } + } + }, + "ListServerlessBillingResponse": { + "type": "object", + "description": "Billing records for serverless.", + "required": [ + "records", + "metadata" + ], + "properties": { + "records": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ServerlessBillingRecord" + } + }, + "metadata": { + "$ref": "#/components/schemas/ServerlessBillingMetadata" + } + } + }, + "ListEndpointBillingResponse": { + "type": "object", + "description": "Billing records for RunPod public endpoints.", + "required": [ + "records", + "metadata" + ], + "properties": { + "records": { + "type": "array", + "items": { + "$ref": "#/components/schemas/EndpointBillingRecord" + } + }, + "metadata": { + "$ref": "#/components/schemas/EndpointBillingMetadata" + } + } + }, + "ListNetworkVolumeBillingResponse": { + "type": "object", + "description": "Billing records for network volumes.", + "required": [ + "records", + "metadata" + ], + "properties": { + "records": { + "type": "array", + "items": { + "$ref": "#/components/schemas/NetworkVolumeBillingRecord" + } + }, + "metadata": { + "$ref": "#/components/schemas/NetworkVolumeBillingMetadata" + } + } + }, + "ListClusterBillingResponse": { + "type": "object", + "description": "Billing records for Instant Clusters.", + "required": [ + "records", + "metadata" + ], + "properties": { + "records": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ClusterBillingRecord" + } + }, + "metadata": { + "$ref": "#/components/schemas/ClusterBillingMetadata" + } + } + }, + "ErrorResponse": { + "type": "object", + "properties": { + "title": { + "type": "string", + "description": "Short human-readable summary", + "example": "Not Found" + }, + "status": { + "type": "integer", + "description": "HTTP status code", + "example": 404 + }, + "detail": { + "type": "string", + "description": "Human-readable explanation", + "example": "pod not found" + } + } + }, + "ValidatationErrorResponse": { + "type": "object", + "properties": { + "title": { + "type": "string", + "description": "Short human-readable summary", + "example": "Unprocessable Entity" + }, + "status": { + "type": "integer", + "description": "HTTP status code", + "example": 422 + }, + "errors": { + "type": "array", + "items": { + "type": "string", + "example": "$: minProperties: got 0, want 1" + }, + "description": "Human-readable explanation" + } + } + } + } + }, + "paths": { + "/v2/pods": { + "get": { + "operationId": "listPods", + "summary": "List pods", + "description": "Returns all pods owned by the authenticated user.", + "tags": [ + "Pods" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListPodsResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + }, + "post": { + "operationId": "createPod", + "summary": "Create a pod", + "description": "Creates a new pod. Specify `gpu` for compute.\nContainerConfig fields can be spread from a template response.\n", + "tags": [ + "Pods" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreatePodRequest" + } + } + } + }, + "responses": { + "201": { + "description": "Created", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Pod" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/pods/{id}": { + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "Pod identifier", + "example": "pod_abc123" + } + ], + "get": { + "operationId": "getPod", + "summary": "Get a pod", + "description": "Returns a single pod by ID.", + "tags": [ + "Pods" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Pod" + } + } + } + }, + "404": { + "description": "Pod not found", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + }, + "patch": { + "operationId": "updatePod", + "summary": "Update a pod", + "description": "Updates pod configuration. Only provided fields are changed.", + "tags": [ + "Pods" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdatePodRequest" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Pod" + } + } + } + }, + "404": { + "description": "Pod not found", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + }, + "delete": { + "operationId": "deletePod", + "summary": "Terminate a pod", + "description": "Permanently terminates and deletes a pod.", + "tags": [ + "Pods" + ], + "responses": { + "204": { + "description": "Terminated" + }, + "404": { + "description": "Pod not found", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/pods/{id}/action": { + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "example": "pod_abc123" + } + ], + "post": { + "operationId": "podAction", + "summary": "Trigger a pod state transition", + "description": "Triggers a state transition on a pod. Valid actions depend on the current status\nand are listed in the pod's `actions` field.\n", + "tags": [ + "Pods" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PodActionRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Action applied — returns updated pod", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Pod" + } + } + } + }, + "204": { + "description": "Pod terminated (for action=terminate)" + }, + "404": { + "description": "Pod not found", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Action not valid for current pod status", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/serverless": { + "get": { + "operationId": "listEndpoints", + "summary": "List serverless endpoints", + "description": "Returns all serverless endpoints owned by the authenticated user.", + "tags": [ + "Serverless" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListEndpointsResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + }, + "post": { + "operationId": "createEndpoint", + "summary": "Create a serverless endpoint", + "description": "Creates a serverless endpoint. Specify `gpu` for compute (CPU serverless\nendpoints are read-only). ContainerConfig fields can be spread from a\ntemplate response.\n", + "tags": [ + "Serverless" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateEndpointRequest" + } + } + } + }, + "responses": { + "201": { + "description": "Created", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Endpoint" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/serverless/{id}": { + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "Serverless endpoint identifier", + "example": "ep_abc123" + } + ], + "get": { + "operationId": "getEndpoint", + "summary": "Get a serverless endpoint", + "description": "Returns a single serverless endpoint by ID.", + "tags": [ + "Serverless" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Endpoint" + } + } + } + }, + "404": { + "description": "Serverless endpoint not found", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + }, + "patch": { + "operationId": "updateEndpoint", + "summary": "Update a serverless endpoint", + "description": "Updates serverless endpoint configuration. Only provided fields are changed.", + "tags": [ + "Serverless" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateEndpointRequest" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Endpoint" + } + } + } + }, + "404": { + "description": "Serverless endpoint not found", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + }, + "delete": { + "operationId": "deleteEndpoint", + "summary": "Delete a serverless endpoint", + "description": "Permanently deletes a serverless endpoint and its bound template.", + "tags": [ + "Serverless" + ], + "responses": { + "204": { + "description": "Deleted" + }, + "404": { + "description": "Serverless endpoint not found", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/serverless/{id}/workers": { + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "Serverless endpoint identifier", + "example": "ep_abc123" + } + ], + "get": { + "operationId": "listEndpointWorkers", + "summary": "List serverless endpoint workers", + "description": "Returns the active workers for a serverless endpoint plus a summary of\nworker counts. Each worker's `status` is derived by reconciling the\nworker pod's lifecycle status with the endpoint's live job-queue view.\nWhen the job-queue view is unavailable the response degrades to the\npod-derived status and counts.\n", + "tags": [ + "Serverless" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListEndpointWorkersResponse" + } + } + } + }, + "404": { + "description": "Serverless endpoint not found", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/templates": { + "get": { + "operationId": "listTemplates", + "summary": "List templates", + "description": "Returns all templates owned by the authenticated user.", + "tags": [ + "Templates" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListTemplatesResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + }, + "post": { + "operationId": "createTemplate", + "summary": "Create a template", + "tags": [ + "Templates" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateTemplateRequest" + } + } + } + }, + "responses": { + "201": { + "description": "Created", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Template" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/templates/{id}": { + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "example": "tpl_abc" + } + ], + "get": { + "operationId": "getTemplate", + "summary": "Get a template", + "tags": [ + "Templates" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Template" + } + } + } + }, + "404": { + "description": "Template not found", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + }, + "patch": { + "operationId": "updateTemplate", + "summary": "Update a template", + "description": "Updates template configuration. Only provided fields are changed.", + "tags": [ + "Templates" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateTemplateRequest" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Template" + } + } + } + }, + "404": { + "description": "Template not found", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + }, + "delete": { + "operationId": "deleteTemplate", + "summary": "Delete a template", + "tags": [ + "Templates" + ], + "responses": { + "204": { + "description": "Deleted" + }, + "404": { + "description": "Template not found", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/tags": { + "get": { + "operationId": "listTags", + "summary": "List tags", + "description": "Returns all tags owned by the authenticated user.", + "tags": [ + "Tags" + ], + "parameters": [ + { + "name": "include", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Comma-separated optional expansions. Supported value: `resources`." + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListTagsResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + }, + "post": { + "operationId": "createTag", + "summary": "Create a tag", + "description": "Creates a user-defined key-value tag.", + "tags": [ + "Tags" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateTagRequest" + } + } + } + }, + "responses": { + "201": { + "description": "Created", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Tag" + } + } + } + }, + "400": { + "description": "Invalid request body", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/tags/{id}": { + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "Tag identifier", + "example": "tag_abc123" + } + ], + "get": { + "operationId": "getTag", + "summary": "Get a tag", + "description": "Returns a single tag by ID.", + "tags": [ + "Tags" + ], + "parameters": [ + { + "name": "include", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Comma-separated optional expansions. Supported value: `resources`." + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Tag" + } + } + } + }, + "404": { + "description": "Tag not found", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + }, + "patch": { + "operationId": "updateTag", + "summary": "Update a tag", + "description": "Updates a tag. At least one of `key`, `value`, or `resources` must be provided.\n\nWhen `resources` is provided, it replaces the tag's complete resource association set. Resource replacement is not atomic: the API creates missing associations first, then deletes stale associations using separate upstream operations. If an upstream operation fails after earlier operations have succeeded, the response is an error and the tag may contain a partially-applied resource set. Retrying the same request with the same `resources` array is safe and will attempt to converge the tag to the requested set. Use the explicit tag-resource attach/detach operations when you need smaller idempotent association changes.\n", + "tags": [ + "Tags" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateTagRequest" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Tag" + } + } + } + }, + "404": { + "description": "Tag not found", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "422": { + "description": "Unprocessable request body (missing one of `key`, `value`, or `resources`)", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + }, + "delete": { + "operationId": "deleteTag", + "summary": "Delete a tag", + "description": "Deletes a tag. This operation is idempotent; deleting a tag that does not exist returns `204`.", + "tags": [ + "Tags" + ], + "responses": { + "204": { + "description": "Deleted or already absent" + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/tags/{id}/resources/{resourceType}/{resourceId}": { + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "Tag identifier", + "example": "tag_abc123" + }, + { + "name": "resourceType", + "in": "path", + "required": true, + "schema": { + "$ref": "#/components/schemas/TagResourceType" + }, + "description": "Resource type to attach or detach." + }, + { + "name": "resourceId", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "Resource identifier to attach or detach.", + "example": "pod_abc123" + } + ], + "put": { + "operationId": "attachTagResource", + "summary": "Attach a resource to a tag", + "description": "Ensures the resource is attached to the tag. This operation is idempotent; attaching an already-associated resource returns `204`.", + "tags": [ + "Tags" + ], + "responses": { + "204": { + "description": "Attached or already associated" + }, + "404": { + "description": "Tag not found", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + }, + "delete": { + "operationId": "detachTagResource", + "summary": "Detach a resource from a tag", + "description": "Ensures the resource is detached from the tag. This operation is idempotent; detaching a resource that is not associated with the tag returns `204`.", + "tags": [ + "Tags" + ], + "responses": { + "204": { + "description": "Detached or already absent" + }, + "404": { + "description": "Tag not found", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/network-volumes": { + "get": { + "operationId": "listNetworkVolumes", + "summary": "List network volumes", + "description": "Returns all network volumes owned by the authenticated user.", + "tags": [ + "Network Volumes" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListNetworkVolumesResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + }, + "post": { + "operationId": "createNetworkVolume", + "summary": "Create a network volume", + "description": "Provisions a new network volume in the specified data center.", + "tags": [ + "Network Volumes" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateNetworkVolumeRequest" + } + } + } + }, + "responses": { + "201": { + "description": "Created", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NetworkVolume" + } + } + } + }, + "400": { + "description": "Invalid request body", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/network-volumes/{id}": { + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "Network volume identifier", + "example": "agv6w2qcg7" + } + ], + "get": { + "operationId": "getNetworkVolume", + "summary": "Get a network volume", + "description": "Returns a single network volume by ID.", + "tags": [ + "Network Volumes" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NetworkVolume" + } + } + } + }, + "404": { + "description": "Network volume not found", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + }, + "patch": { + "operationId": "updateNetworkVolume", + "summary": "Update a network volume", + "description": "Updates mutable fields on a network volume. Only provided fields are changed.\nNote: `size` may only increase; attempts to reduce size will be rejected.\n", + "tags": [ + "Network Volumes" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateNetworkVolumeRequest" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NetworkVolume" + } + } + } + }, + "400": { + "description": "Invalid request body or size decrease attempted", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "404": { + "description": "Network volume not found", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + }, + "delete": { + "operationId": "deleteNetworkVolume", + "summary": "Delete a network volume", + "description": "Permanently deletes a network volume and releases its storage.", + "tags": [ + "Network Volumes" + ], + "responses": { + "204": { + "description": "Deleted" + }, + "404": { + "description": "Network volume not found", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/registries": { + "get": { + "operationId": "listRegistries", + "summary": "List container registries", + "description": "Returns all container registry credentials owned by the authenticated user.", + "tags": [ + "Registries" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListRegistriesResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + }, + "post": { + "operationId": "createRegistry", + "summary": "Create a container registry credential", + "description": "Stores credentials for a private container registry. Credentials are write-only.", + "tags": [ + "Registries" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateRegistryRequest" + } + } + } + }, + "responses": { + "201": { + "description": "Created", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Registry" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/registries/{id}": { + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "example": "reg_abc" + } + ], + "get": { + "operationId": "getRegistry", + "summary": "Get a container registry credential", + "tags": [ + "Registries" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Registry" + } + } + } + }, + "404": { + "description": "Registry not found", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + }, + "delete": { + "operationId": "deleteRegistry", + "summary": "Delete a container registry credential", + "tags": [ + "Registries" + ], + "responses": { + "204": { + "description": "Deleted" + }, + "404": { + "description": "Registry not found", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/catalog/gpus": { + "get": { + "operationId": "listGpuTypes", + "summary": "List GPU types", + "description": "Returns available GPU types with pricing. Availability is included only when requested with include=AVAILABILITY.", + "tags": [ + "Catalog" + ], + "parameters": [ + { + "$ref": "#/components/parameters/CatalogIncludeParam" + }, + { + "$ref": "#/components/parameters/GpuProductFilter" + }, + { + "$ref": "#/components/parameters/GpuCountFilter" + }, + { + "$ref": "#/components/parameters/GpuCloudFilter" + }, + { + "$ref": "#/components/parameters/MinCudaVersionFilter" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListGpuTypesResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/catalog/gpus/{id}": { + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "example": "NVIDIA GeForce RTX 4090" + } + ], + "get": { + "operationId": "getGpuType", + "summary": "Get a GPU type", + "description": "Returns a single GPU type with pricing. Availability details are included only when requested with include=AVAILABILITY.", + "tags": [ + "Catalog" + ], + "parameters": [ + { + "$ref": "#/components/parameters/CatalogIncludeParam" + }, + { + "$ref": "#/components/parameters/GpuProductFilter" + }, + { + "$ref": "#/components/parameters/GpuCountFilter" + }, + { + "$ref": "#/components/parameters/GpuCloudFilter" + }, + { + "$ref": "#/components/parameters/MinCudaVersionFilter" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GpuType" + } + } + } + }, + "404": { + "description": "GPU type not found", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/catalog/cpus": { + "get": { + "operationId": "listCpuTypes", + "summary": "List CPU types", + "description": "Returns available CPU flavors. Availability is included only when requested with include=AVAILABILITY.", + "tags": [ + "Catalog" + ], + "parameters": [ + { + "$ref": "#/components/parameters/CatalogIncludeParam" + }, + { + "$ref": "#/components/parameters/CpuProductFilter" + }, + { + "$ref": "#/components/parameters/CpuVCPUCountFilter" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListCpuTypesResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/catalog/cpus/{id}": { + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "example": "cpu5c" + } + ], + "get": { + "operationId": "getCpuType", + "summary": "Get a CPU type", + "description": "Returns a single CPU type with pricing. Availability details are included only when requested with include=AVAILABILITY.", + "tags": [ + "Catalog" + ], + "parameters": [ + { + "$ref": "#/components/parameters/CatalogIncludeParam" + }, + { + "$ref": "#/components/parameters/CpuProductFilter" + }, + { + "$ref": "#/components/parameters/CpuVCPUCountFilter" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CpuType" + } + } + } + }, + "404": { + "description": "CPU type not found", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/catalog/datacenters": { + "get": { + "operationId": "listDataCenters", + "summary": "List data centers", + "description": "Returns available data center locations.", + "tags": [ + "Catalog" + ], + "parameters": [ + { + "name": "include", + "in": "query", + "required": false, + "description": "Comma-separated optional expansions. Supported value: GPU_AVAILABILITY, CPU_AVAILABILITY.", + "style": "form", + "explode": false, + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/DataCenterInclude" + }, + "example": [ + "GPU_AVAILABILITY" + ] + } + }, + { + "name": "regions", + "in": "query", + "required": false, + "description": "Comma-separated DataCenterRegion enum values. Values within this filter use OR semantics. Different filter families combine with AND.", + "style": "form", + "explode": false, + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/DataCenterRegion" + }, + "example": [ + "EUROPE", + "ASIA" + ] + } + }, + { + "name": "networkVolumeTypes", + "in": "query", + "required": false, + "description": "Comma-separated volume types. Supported values: STANDARD, HIGH_PERFORMANCE. Values within this filter use AND semantics; volumes=STANDARD,HIGH_PERFORMANCE requires both storage types. Different filter families combine with AND.", + "style": "form", + "explode": false, + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/VolumeType" + }, + "example": [ + "STANDARD", + "HIGH_PERFORMANCE" + ] + } + }, + { + "name": "compliance", + "in": "query", + "required": false, + "description": "Comma-separated Compliance enum values. Values within this filter use AND semantics; compliance=GDPR,SOC_2_TYPE_2 requires both certifications. Different filter families combine with AND.", + "style": "form", + "explode": false, + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Compliance" + }, + "example": [ + "GDPR", + "SOC_2_TYPE_2" + ] + } + }, + { + "name": "globalNetwork", + "in": "query", + "required": false, + "description": "Filter by global networking support. true returns only data centers that support global networking; false only those that do not. Different filter families combine with AND.", + "schema": { + "type": "boolean" + }, + "example": true + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListDataCentersResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/catalog/datacenters/{id}": { + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "example": "US-CA-2" + } + ], + "get": { + "operationId": "getDataCenter", + "summary": "Get a data center", + "description": "Returns a single data center. Availability is included only when requested with include=GPU_AVAILABILITY or include=CPU_AVAILABILITY.", + "tags": [ + "Catalog" + ], + "parameters": [ + { + "name": "include", + "in": "query", + "required": false, + "description": "Comma-separated optional expansions. Supported value: GPU_AVAILABILITY, CPU_AVAILABILITY.", + "style": "form", + "explode": false, + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/DataCenterInclude" + }, + "example": [ + "GPU_AVAILABILITY" + ] + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DataCenter" + } + } + } + }, + "404": { + "description": "Data center not found", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/billing": { + "get": { + "operationId": "listBilling", + "summary": "Get aggregated billing history", + "description": "Returns time-bucketed total spend across all billable RunPod resources for the authenticated user over the requested period, with each cost component broken out.\n", + "tags": [ + "Billing" + ], + "parameters": [ + { + "$ref": "#/components/parameters/BillingStartTime" + }, + { + "$ref": "#/components/parameters/BillingEndTime" + }, + { + "$ref": "#/components/parameters/BillingBucketSize" + }, + { + "$ref": "#/components/parameters/BillingLastN" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListBillingResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/billing/pods": { + "get": { + "operationId": "listPodBilling", + "summary": "Get pod billing history", + "description": "Returns time-bucketed pod billing records (GPU and CPU pods) for the authenticated user over the requested period.\n", + "tags": [ + "Billing" + ], + "parameters": [ + { + "$ref": "#/components/parameters/BillingStartTime" + }, + { + "$ref": "#/components/parameters/BillingEndTime" + }, + { + "$ref": "#/components/parameters/BillingBucketSize" + }, + { + "$ref": "#/components/parameters/BillingLastN" + }, + { + "name": "podId", + "in": "query", + "required": false, + "description": "Filter to a specific pod (GPU or CPU).", + "schema": { + "type": "string" + }, + "example": "pod_abc123" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListPodBillingResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/billing/serverless": { + "get": { + "operationId": "listServerlessBilling", + "summary": "Get serverless billing history", + "description": "Returns time-bucketed serverless billing records for the authenticated user over the requested period.\n", + "tags": [ + "Billing" + ], + "parameters": [ + { + "$ref": "#/components/parameters/BillingStartTime" + }, + { + "$ref": "#/components/parameters/BillingEndTime" + }, + { + "$ref": "#/components/parameters/BillingBucketSize" + }, + { + "$ref": "#/components/parameters/BillingLastN" + }, + { + "name": "serverlessId", + "in": "query", + "required": false, + "description": "Filter to a specific serverless endpoint.", + "schema": { + "type": "string" + }, + "example": "jpnw0v75y3qoql" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListServerlessBillingResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/billing/endpoints": { + "get": { + "operationId": "listEndpointBilling", + "summary": "Get public endpoint billing history", + "description": "Returns time-bucketed RunPod public endpoint billing records for the authenticated user over the requested period.\n", + "tags": [ + "Billing" + ], + "parameters": [ + { + "$ref": "#/components/parameters/BillingStartTime" + }, + { + "$ref": "#/components/parameters/BillingEndTime" + }, + { + "$ref": "#/components/parameters/BillingBucketSize" + }, + { + "$ref": "#/components/parameters/BillingLastN" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListEndpointBillingResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/billing/networkvolumes": { + "get": { + "operationId": "listNetworkVolumeBilling", + "summary": "Get network volume billing history", + "description": "Returns time-bucketed network volume billing records for the authenticated user over the requested period.\n", + "tags": [ + "Billing" + ], + "parameters": [ + { + "$ref": "#/components/parameters/BillingStartTime" + }, + { + "$ref": "#/components/parameters/BillingEndTime" + }, + { + "$ref": "#/components/parameters/BillingBucketSize" + }, + { + "$ref": "#/components/parameters/BillingLastN" + }, + { + "name": "networkVolumeId", + "in": "query", + "required": false, + "description": "Filter to a specific network volume.", + "schema": { + "type": "string" + }, + "example": "vol_abc123" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListNetworkVolumeBillingResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/billing/clusters": { + "get": { + "operationId": "listClusterBilling", + "summary": "Get Instant Cluster billing history", + "description": "Returns time-bucketed Instant Cluster billing records for the authenticated user over the requested period.\n", + "tags": [ + "Billing" + ], + "parameters": [ + { + "$ref": "#/components/parameters/BillingStartTime" + }, + { + "$ref": "#/components/parameters/BillingEndTime" + }, + { + "$ref": "#/components/parameters/BillingBucketSize" + }, + { + "$ref": "#/components/parameters/BillingLastN" + }, + { + "name": "clusterId", + "in": "query", + "required": false, + "description": "Filter to a specific Instant Cluster.", + "schema": { + "type": "string" + }, + "example": "cluster_abc123" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListClusterBillingResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + } + } +} \ No newline at end of file From 5179d62e2a0d5cf373f4535195dfa38ec5a407e5 Mon Sep 17 00:00:00 2001 From: lgunreddi Date: Mon, 29 Jun 2026 11:56:52 -0400 Subject: [PATCH 07/41] Update openapi.json --- api-reference-v2/openapi.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api-reference-v2/openapi.json b/api-reference-v2/openapi.json index 1415e01e..c4ad3127 100644 --- a/api-reference-v2/openapi.json +++ b/api-reference-v2/openapi.json @@ -5037,4 +5037,4 @@ } } } -} \ No newline at end of file +} From 2a92a91ce9ef5cfe1616a34bfe28915357822b39 Mon Sep 17 00:00:00 2001 From: lgunreddi Date: Thu, 2 Jul 2026 12:01:35 -0400 Subject: [PATCH 08/41] Update docs.json --- docs.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs.json b/docs.json index ee973039..52fdee7e 100644 --- a/docs.json +++ b/docs.json @@ -512,7 +512,7 @@ ] }, { - "tab": "API v2", + "tab": "REST API", "groups": [ { "group": "REST API v2", From 945d0b10ef6da3e94623b9d3dfd31fb24bb391c8 Mon Sep 17 00:00:00 2001 From: lgunreddi Date: Thu, 2 Jul 2026 12:33:51 -0400 Subject: [PATCH 09/41] Update docs.json --- docs.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs.json b/docs.json index 52fdee7e..4db19a21 100644 --- a/docs.json +++ b/docs.json @@ -512,7 +512,7 @@ ] }, { - "tab": "REST API", + "tab": "REST API (BETA)", "groups": [ { "group": "REST API v2", From 40bdd48f2fed108df1446c346ca06858bf88c6ae Mon Sep 17 00:00:00 2001 From: lgunreddi Date: Thu, 2 Jul 2026 13:09:46 -0400 Subject: [PATCH 10/41] Update openapi.json From 26b55cd829b6844e23cec75524beb3d0cba8cae4 Mon Sep 17 00:00:00 2001 From: lgunreddi Date: Thu, 2 Jul 2026 13:32:58 -0400 Subject: [PATCH 11/41] Update docs.json --- docs.json | 82 ++++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 69 insertions(+), 13 deletions(-) diff --git a/docs.json b/docs.json index 4db19a21..30b964fc 100644 --- a/docs.json +++ b/docs.json @@ -512,14 +512,14 @@ ] }, { - "tab": "REST API (BETA)", - "groups": [ - { - "group": "REST API v2", - "pages": [ - "api-reference-v2/overview" - ] - }, + "tab": "REST API (BETA)", + "groups": [ + { + "group": "REST API v2", + "pages": [ + "api-reference-v2/overview" + ] + }, { "group": "Pods", "openapi": "api-reference-v2/openapi.json", @@ -532,25 +532,81 @@ "POST /v2/pods/{id}/action" ] }, + { + "group": "Serverless", + "openapi": "api-reference-v2/openapi.json", + "pages": [ + "GET /v2/serverless", + "POST /v2/serverless", + "GET /v2/serverless/{id}", + "PATCH /v2/serverless/{id}", + "DELETE /v2/serverless/{id}", + "GET /v2/serverless/{id}/workers" + ] + }, { "group": "Templates", "openapi": "api-reference-v2/openapi.json", "pages": [ "GET /v2/templates", "POST /v2/templates", - "GET /v2/templates/{id}" + "GET /v2/templates/{id}", + "PATCH /v2/templates/{id}", + "DELETE /v2/templates/{id}" ] }, { "group": "Network Volumes", "openapi": "api-reference-v2/openapi.json", "pages": [ - "GET /v2/network-volumes", - "POST /v2/network-volumes" + "GET /v2/networkvolumes", + "POST /v2/networkvolumes", + "GET /v2/networkvolumes/{id}", + "PATCH /v2/networkvolumes/{id}", + "DELETE /v2/networkvolumes/{id}" + ] + }, + { + "group": "Tags", + "openapi": "api-reference-v2/openapi.json", + "pages": [ + "GET /v2/tags", + "POST /v2/tags", + "GET /v2/tags/{id}", + "PATCH /v2/tags/{id}", + "DELETE /v2/tags/{id}", + "PUT /v2/tags/{id}/resources/{resourceType}/{resourceId}", + "DELETE /v2/tags/{id}/resources/{resourceType}/{resourceId}" + ] + }, + { + "group": "Container Registry Auths", + "openapi": "api-reference-v2/openapi.json", + "pages": [ + "GET /v2/containerregistryauth", + "POST /v2/containerregistryauth", + "GET /v2/containerregistryauth/{id}", + "DELETE /v2/containerregistryauth/{id}" + ] + }, + { + "group": "Catalog", + "openapi": "api-reference-v2/openapi.json", + "pages": [ + "GET /v2/catalog/gpus", + "GET /v2/catalog/cpus", + "GET /v2/catalog/datacenters" + ] + }, + { + "group": "Billing", + "openapi": "api-reference-v2/openapi.json", + "pages": [ + "GET /v2/billing" ] } - ] - }, + ] +}, { "tab": "Models", "groups": [ From 6f6d9ca3e22647686e4795b4b264d0f523d9b464 Mon Sep 17 00:00:00 2001 From: lgunreddi Date: Thu, 2 Jul 2026 14:42:03 -0400 Subject: [PATCH 12/41] Update openapi.json --- api-reference-v2/openapi.json | 524 +++++++++++++++++++++++++++++++++- 1 file changed, 515 insertions(+), 9 deletions(-) diff --git a/api-reference-v2/openapi.json b/api-reference-v2/openapi.json index c4ad3127..f3a4c735 100644 --- a/api-reference-v2/openapi.json +++ b/api-reference-v2/openapi.json @@ -138,9 +138,16 @@ "name": "product", "in": "query", "required": false, - "description": "Availability product context. Valid only with include=AVAILABILITY. Supported values for CPUs: POD, SERVERLESS. Upstream default when omitted: POD.", + "description": "Comma-separated availability product context. Valid only with include=AVAILABILITY. Supported values for CPUs: POD, SERVERLESS. Defaults to POD when omitted.", "schema": { - "$ref": "#/components/schemas/CpuProduct" + "type": "array", + "items": { + "$ref": "#/components/schemas/CpuProduct" + }, + "example": [ + "POD", + "SERVERLESS" + ] } }, "CpuVCPUCountFilter": { @@ -153,6 +160,47 @@ "minimum": 2 }, "example": 4 + }, + "LogSourceParam": { + "name": "source", + "in": "query", + "required": false, + "description": "Log source to stream. Omit to include both container and system logs.", + "schema": { + "$ref": "#/components/schemas/LogSource" + } + }, + "LogTail": { + "name": "tail", + "in": "query", + "required": false, + "description": "Number of historical lines to backfill before streaming. Defaults to\n100 when omitted; set `0` to stream live with no backfill. Maximum 5000.\nIgnored when `since` or `Last-Event-ID` is provided — the resume cursor\ndrives the backfill instead.\n", + "schema": { + "type": "integer", + "minimum": 0, + "maximum": 5000, + "default": 100 + } + }, + "LogSince": { + "name": "since", + "in": "query", + "required": false, + "description": "RFC3339 timestamp to resume from. Ignored when `Last-Event-ID` is\nprovided. When set, the stream resumes from this point and `tail` is\nignored.\n", + "schema": { + "type": "string", + "format": "date-time" + } + }, + "LogLastEventID": { + "name": "Last-Event-ID", + "in": "header", + "required": false, + "description": "SSE reconnect cursor — a timestamp emitted by this endpoint. Takes\nprecedence over `since` and `tail`: when present, the stream resumes\nfrom this point. Sent automatically by EventSource on reconnect.\n", + "schema": { + "type": "string", + "format": "date-time" + } } }, "schemas": { @@ -682,6 +730,155 @@ } } }, + "ReleaseSource": { + "type": "string", + "description": "What produced the release.\n- `GIT_BUILD` — a completed GitHub build (see `buildId`)\n- `MANUAL` — a manual configuration change\n", + "x-enum-varnames": [ + "ReleaseSourceGitBuild", + "ReleaseSourceManual" + ], + "enum": [ + "GIT_BUILD", + "MANUAL" + ] + }, + "ReleaseDiffEntry": { + "type": "object", + "required": [ + "field", + "old", + "new" + ], + "properties": { + "field": { + "type": "string", + "description": "The changed configuration field. Top-level (e.g. `gpuCount`,\n`locations`) or template-scoped (e.g. `template.imageName`,\n`template.env`).\n", + "example": "template.imageName" + }, + "old": { + "nullable": true, + "description": "Previous value, as raw JSON. Null when the field was added." + }, + "new": { + "nullable": true, + "description": "New value, as raw JSON. Null when the field was removed." + } + } + }, + "Release": { + "type": "object", + "required": [ + "id", + "source", + "createdAt", + "workerCount", + "diff" + ], + "properties": { + "id": { + "type": "string", + "example": "rel_abc123" + }, + "version": { + "type": "integer", + "nullable": true, + "description": "The endpoint configuration version this release produced.", + "example": 4 + }, + "source": { + "$ref": "#/components/schemas/ReleaseSource" + }, + "buildId": { + "type": "string", + "nullable": true, + "description": "The GitHub build that produced this release. Set when `source` is\n`GIT_BUILD`; null for `MANUAL` releases. Fetch build detail/logs via\n`/v2/serverless/{id}/builds/{buildId}`.\n", + "example": "build_abc123" + }, + "createdByUserId": { + "type": "string", + "nullable": true, + "description": "ID of the user who created the release." + }, + "workerCount": { + "type": "integer", + "minimum": 0, + "description": "Workers currently running this release's version.", + "example": 2 + }, + "createdAt": { + "type": "string", + "format": "date-time", + "example": "2026-03-13T20:00:00Z" + }, + "diff": { + "type": "array", + "description": "Configuration fields that changed in this release.", + "items": { + "$ref": "#/components/schemas/ReleaseDiffEntry" + } + } + } + }, + "RolloutSummary": { + "type": "object", + "required": [ + "inProgress", + "workersOnLatest", + "workersTotal", + "percentOnLatest" + ], + "properties": { + "inProgress": { + "type": "boolean", + "description": "True while any worker is still running an older version.", + "example": true + }, + "workersOnLatest": { + "type": "integer", + "minimum": 0, + "description": "Workers running the endpoint's current version.", + "example": 2 + }, + "workersTotal": { + "type": "integer", + "minimum": 0, + "description": "All workers currently allocated to the endpoint.", + "example": 3 + }, + "percentOnLatest": { + "type": "integer", + "minimum": 0, + "maximum": 100, + "description": "Percentage of workers on the current version (0 when there are no workers).", + "example": 67 + } + } + }, + "ListEndpointReleasesResponse": { + "type": "object", + "required": [ + "rollout", + "releases" + ], + "properties": { + "endpointVersion": { + "type": "integer", + "nullable": true, + "description": "The endpoint's current configuration version. Null if unknown.", + "example": 4 + }, + "rollout": { + "$ref": "#/components/schemas/RolloutSummary" + }, + "releases": { + "type": "array", + "description": "Release history, newest first.", + "items": { + "$ref": "#/components/schemas/Release" + } + } + } + }, "CreateEndpointRequest": { "allOf": [ { @@ -932,6 +1129,18 @@ "terminate" ] }, + "LogSource": { + "type": "string", + "description": "Log source to include in a log stream.\n- `container` — container stdout/stderr log stream\n- `system` — host lifecycle/userlogs stream\n", + "x-enum-varnames": [ + "LogSourceContainer", + "LogSourceSystem" + ], + "enum": [ + "container", + "system" + ] + }, "Cloud": { "type": "string", "description": "Cloud tier.\n- `SECURE` — RunPod-owned datacenter hardware\n- `COMMUNITY` — community-hosted hardware\n- `ALL` — eligible for either tier (request-only; responses always\n report the concrete tier the pod was placed on)\n", @@ -1469,6 +1678,7 @@ "name", "size", "dataCenter", + "type", "tags" ], "properties": { @@ -1484,8 +1694,8 @@ }, "size": { "type": "integer", - "minimum": 1, - "maximum": 4000, + "minimum": 10, + "maximum": 4096, "description": "Allocated storage in GB", "example": 50 }, @@ -1494,6 +1704,14 @@ "description": "Data center location; immutable after creation", "example": "EU-RO-1" }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/VolumeType" + } + ], + "description": "Storage tier of this volume. Set at creation and immutable." + }, "tags": { "type": "array", "description": "Tags attached to this network volume.", @@ -1519,8 +1737,8 @@ }, "size": { "type": "integer", - "minimum": 1, - "maximum": 4000, + "minimum": 10, + "maximum": 4096, "description": "Storage to allocate in GB", "example": 50 }, @@ -1529,12 +1747,22 @@ "minLength": 1, "description": "Data center in which to create the volume", "example": "EU-RO-1" + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/VolumeType" + } + ], + "description": "Storage tier for the volume. Optional. When omitted, the volume is\nprovisioned using the requested data center's default (primary)\nstorage tier. HIGH_PERFORMANCE provisions a high-performance (HPS)\nvolume; STANDARD provisions a standard volume. A volume's tier is\nimmutable after creation.\n" } } }, "UpdateNetworkVolumeRequest": { "type": "object", - "description": "All fields are optional. Only provided fields are updated.", + "additionalProperties": false, + "minProperties": 1, + "description": "Only the provided fields are updated. At least one field must be\npresent; an empty body is rejected.\n", "properties": { "name": { "type": "string", @@ -1544,8 +1772,8 @@ }, "size": { "type": "integer", - "minimum": 1, - "maximum": 4000, + "minimum": 10, + "maximum": 4096, "description": "New size in GB. Must be greater than or equal to the current size —\nnetwork volume storage cannot be reduced.\n", "example": 100 } @@ -3038,6 +3266,113 @@ } } }, + "/v2/pods/{id}/logs": { + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "Pod identifier", + "example": "pod_abc123" + } + ], + "get": { + "operationId": "getPodLogs", + "summary": "Stream pod logs", + "description": "Streams pod logs as Server-Sent Events. The `source` query parameter\nselects which log source to include.\n\nThe SSE `data` payload shape is:\n`{ \"source\": \"container\", \"line\": \"...\", \"ts\": \"...\" }`.\nLog-event `id` values are the event `ts` timestamp so\nbrowser/EventSource reconnects can resume with `Last-Event-ID`.\n", + "tags": [ + "Pods" + ], + "parameters": [ + { + "$ref": "#/components/parameters/LogSourceParam" + }, + { + "$ref": "#/components/parameters/LogTail" + }, + { + "$ref": "#/components/parameters/LogSince" + }, + { + "$ref": "#/components/parameters/LogLastEventID" + } + ], + "responses": { + "200": { + "description": "Pod log event stream", + "headers": { + "Cache-Control": { + "schema": { + "type": "string" + }, + "description": "Always `no-cache` for SSE responses." + }, + "Connection": { + "schema": { + "type": "string" + }, + "description": "Always `keep-alive` to hold the SSE stream open." + }, + "X-Accel-Buffering": { + "schema": { + "type": "string" + }, + "description": "Always `no` to disable proxy buffering of the SSE stream." + } + }, + "content": { + "text/event-stream": { + "schema": { + "type": "object", + "properties": { + "source": { + "type": "string", + "enum": [ + "container", + "system" + ], + "example": "container" + }, + "line": { + "type": "string", + "example": "Model loaded." + }, + "ts": { + "type": "string", + "format": "date-time", + "example": "2026-05-01T22:00:00Z" + } + } + } + } + } + }, + "404": { + "description": "Pod not found", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, "/v2/pods/{id}/action": { "parameters": [ { @@ -3377,6 +3712,177 @@ } } }, + "/v2/serverless/{id}/releases": { + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "Serverless endpoint identifier", + "example": "ep_abc123" + } + ], + "get": { + "operationId": "listEndpointReleases", + "summary": "List serverless endpoint releases", + "description": "Returns the endpoint's release history (newest first) plus a rollout\nsummary of how many workers are running the current version. Each\nrelease is a versioned configuration snapshot with a `diff` of what\nchanged; build-driven releases carry a `buildId` (fetch build detail via\nthe builds sub-routes).\n", + "tags": [ + "Serverless" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListEndpointReleasesResponse" + } + } + } + }, + "404": { + "description": "Serverless endpoint not found", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/serverless/{id}/workers/{workerId}/logs": { + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "Serverless endpoint identifier", + "example": "ep_abc123" + }, + { + "name": "workerId", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "Worker identifier (from GET /v2/serverless/{id}/workers)", + "example": "worker_abc" + } + ], + "get": { + "operationId": "getWorkerLogs", + "summary": "Stream serverless worker logs", + "description": "Streams a serverless worker's logs as Server-Sent Events. The `source`\nquery parameter selects which log source to include.\n\nThe SSE `data` payload shape is:\n`{ \"source\": \"container\", \"line\": \"...\", \"ts\": \"...\" }`.\nLog-event `id` values are the event `ts` timestamp so browser/EventSource\nreconnects can resume with `Last-Event-ID`.\n", + "tags": [ + "Serverless" + ], + "parameters": [ + { + "$ref": "#/components/parameters/LogSourceParam" + }, + { + "$ref": "#/components/parameters/LogTail" + }, + { + "$ref": "#/components/parameters/LogSince" + }, + { + "$ref": "#/components/parameters/LogLastEventID" + } + ], + "responses": { + "200": { + "description": "Worker log event stream", + "headers": { + "Cache-Control": { + "schema": { + "type": "string" + }, + "description": "Always `no-cache` for SSE responses." + }, + "Connection": { + "schema": { + "type": "string" + }, + "description": "Always `keep-alive` to hold the SSE stream open." + }, + "X-Accel-Buffering": { + "schema": { + "type": "string" + }, + "description": "Always `no` to disable proxy buffering of the SSE stream." + } + }, + "content": { + "text/event-stream": { + "schema": { + "type": "object", + "properties": { + "source": { + "type": "string", + "enum": [ + "container", + "system" + ], + "example": "container" + }, + "line": { + "type": "string", + "example": "Model loaded." + }, + "ts": { + "type": "string", + "format": "date-time", + "example": "2026-05-01T22:00:00Z" + } + } + } + } + } + }, + "404": { + "description": "Worker not found", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, "/v2/templates": { "get": { "operationId": "listTemplates", From 74a637c9a956d8a936a54539d08d023b8faac426 Mon Sep 17 00:00:00 2001 From: lgunreddi Date: Thu, 2 Jul 2026 14:49:35 -0400 Subject: [PATCH 13/41] Update overview.mdx --- api-reference-v2/overview.mdx | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/api-reference-v2/overview.mdx b/api-reference-v2/overview.mdx index 5f72a110..aede29d6 100644 --- a/api-reference-v2/overview.mdx +++ b/api-reference-v2/overview.mdx @@ -13,7 +13,7 @@ The Runpod REST API v2 provides programmatic access to your Runpod resources ove ## Base URL ``` -https://rest.runpod.io/v2 +https://api.runpod.io/v2 ``` ## Authentication @@ -32,14 +32,14 @@ Here's a simple request to list your Pods: ```bash cURL curl --request GET \ - --url https://rest.runpod.io/v2/pods \ + --url https://api.runpod.io/v2/pods \ --header 'Authorization: Bearer YOUR_RUNPOD_API_KEY' ``` ```python Python import requests -url = "https://rest.runpod.io/v2/pods" +url = "https://api.runpod.io/v2/pods" headers = {"Authorization": "Bearer YOUR_RUNPOD_API_KEY"} response = requests.get(url, headers=headers) @@ -47,7 +47,7 @@ print(response.json()) ``` ```javascript JavaScript -const response = await fetch("https://rest.runpod.io/v2/pods", { +const response = await fetch("https://api.runpod.io/v2/pods", { headers: { Authorization: "Bearer YOUR_RUNPOD_API_KEY", }, @@ -77,7 +77,7 @@ Retrieve the full OpenAPI spec for client generation or tooling: ```bash curl --request GET \ - --url https://rest.runpod.io/v2/openapi.json \ + --url https://api.runpod.io/v2/openapi.json \ --header 'Authorization: Bearer YOUR_RUNPOD_API_KEY' ``` @@ -94,7 +94,7 @@ REST API v2 is a redesigned, REST-native interface replacing the v1 API. Key imp | | v1 | v2 | |---|---|---| -| Base URL | `rest.runpod.io/v1` | `rest.runpod.io/v2` | +| Base URL | `api.runpod.io/v1` | `api.runpod.io/v2` | | Spec format | OpenAPI 3.0 | OpenAPI 3.0 | | Endpoint management | Full CRUD | Read-only (beta) | | Authentication | Bearer token | Bearer token | From 4ce0186cd8675dddedf6155c0fc90020bc0b82bb Mon Sep 17 00:00:00 2001 From: lgunreddi Date: Thu, 2 Jul 2026 14:51:01 -0400 Subject: [PATCH 14/41] Update overview.mdx --- api-reference-v2/overview.mdx | 13 ------------- 1 file changed, 13 deletions(-) diff --git a/api-reference-v2/overview.mdx b/api-reference-v2/overview.mdx index aede29d6..3d814489 100644 --- a/api-reference-v2/overview.mdx +++ b/api-reference-v2/overview.mdx @@ -67,10 +67,6 @@ console.log(data); | **Container registry auths** | Connect to private Docker registries | | **Billing** | Retrieve usage and billing history | - - Endpoint management (create, update, delete) is not yet available in REST API v2. Use the [GraphQL API](/api-reference/overview) for full endpoint control in the meantime. - - ## OpenAPI specification Retrieve the full OpenAPI spec for client generation or tooling: @@ -90,15 +86,6 @@ REST API v2 is a redesigned, REST-native interface replacing the v1 API. Key imp - OpenAPI 3.0 spec for easy client generation - Improved validation and error messages -## Differences from v1 - -| | v1 | v2 | -|---|---|---| -| Base URL | `api.runpod.io/v1` | `api.runpod.io/v2` | -| Spec format | OpenAPI 3.0 | OpenAPI 3.0 | -| Endpoint management | Full CRUD | Read-only (beta) | -| Authentication | Bearer token | Bearer token | - ## Error responses The API returns standard HTTP status codes: From e7686c930a2d97a429cc66954f96fc7ad0577798 Mon Sep 17 00:00:00 2001 From: lgunreddi Date: Thu, 2 Jul 2026 15:01:17 -0400 Subject: [PATCH 15/41] Update overview.mdx --- api-reference-v2/overview.mdx | 105 ++++++---------------------------- 1 file changed, 19 insertions(+), 86 deletions(-) diff --git a/api-reference-v2/overview.mdx b/api-reference-v2/overview.mdx index 3d814489..0a355342 100644 --- a/api-reference-v2/overview.mdx +++ b/api-reference-v2/overview.mdx @@ -15,107 +15,40 @@ The Runpod REST API v2 provides programmatic access to your Runpod resources ove ``` https://api.runpod.io/v2 ``` +The Runpod REST API provides programmatic access to all Runpod compute resources. Integrate GPU infrastructure into your applications, workflows, and automation systems. -## Authentication +## Available resources -All requests require a Runpod API key passed as a Bearer token in the `Authorization` header. +- **Pods**: Create and manage persistent GPU instances for development, training, and long-running workloads. +- **Serverless endpoints**: Deploy and scale containerized applications with autoscaling and job monitoring. +- **Network volumes**: Create persistent storage attachable to multiple resources. +- **Templates**: Save and reuse Pod and endpoint configurations. +- **Container registry auth**: Connect to private Docker registries. +- **Billing**: Access usage metrics and billing information. -```bash -Authorization: Bearer YOUR_RUNPOD_API_KEY -``` +## Authentication -To get your API key, go to **Settings → API Keys** in the [Runpod console](https://console.runpod.io). +All requests require a [Runpod API key](/get-started/api-keys) in the request headers. The API uses standard HTTP methods and returns JSON responses. -## Quick start +## OpenAPI schema -Here's a simple request to list your Pods: +Retrieve the complete OpenAPI specification for client generation, request validation, or tooling integration. + + ```bash cURL curl --request GET \ - --url https://api.runpod.io/v2/pods \ - --header 'Authorization: Bearer YOUR_RUNPOD_API_KEY' + --url https://api.runpod.io/v2/openapi.json \ + --header 'Authorization: Bearer RUNPOD_API_KEY' ``` ```python Python import requests -url = "https://api.runpod.io/v2/pods" -headers = {"Authorization": "Bearer YOUR_RUNPOD_API_KEY"} - +url = "https://api.runpod.io/v2/openapi.json" +headers = {"Authorization": "Bearer RUNPOD_API_KEY"} response = requests.get(url, headers=headers) print(response.json()) ``` -```javascript JavaScript -const response = await fetch("https://api.runpod.io/v2/pods", { - headers: { - Authorization: "Bearer YOUR_RUNPOD_API_KEY", - }, -}); -const data = await response.json(); -console.log(data); -``` - -## Available resources - -| Resource | Description | -|---|---| -| **Pods** | Create, start, stop, and delete GPU Pods | -| **Endpoints** | Read Serverless endpoint configuration and status | -| **Network volumes** | Create and manage persistent storage | -| **Templates** | Save and reuse Pod configurations | -| **Container registry auths** | Connect to private Docker registries | -| **Billing** | Retrieve usage and billing history | - -## OpenAPI specification - -Retrieve the full OpenAPI spec for client generation or tooling: - -```bash -curl --request GET \ - --url https://api.runpod.io/v2/openapi.json \ - --header 'Authorization: Bearer YOUR_RUNPOD_API_KEY' -``` - -## What's new in v2 - -REST API v2 is a redesigned, REST-native interface replacing the v1 API. Key improvements: - -- Cleaner, more consistent resource paths -- Standard HTTP status codes and error responses -- OpenAPI 3.0 spec for easy client generation -- Improved validation and error messages - -## Error responses - -The API returns standard HTTP status codes: - -| Code | Meaning | -|---|---| -| `200` | Success | -| `400` | Bad request — check your request body or parameters | -| `401` | Unauthorized — missing or invalid API key | -| `404` | Resource not found | -| `422` | Validation error — invalid field values | -| `429` | Rate limit exceeded | -| `500` | Internal server error | - -Error responses include a JSON body with details: - -```json -{ - "detail": "missing bearer token", - "status": 401, - "title": "Unauthorized" -} -``` - -## Next steps - -Explore the interactive API reference to test endpoints directly in your browser: - -- [Pods](/api-reference/v2/pods) -- [Endpoints](/api-reference/v2/endpoints) -- [Network volumes](/api-reference/v2/network-volumes) -- [Templates](/api-reference/v2/templates) -- [Billing](/api-reference/v2/billing) + From 00e874f042faf2cbb5a2098964ad34b6b12090e1 Mon Sep 17 00:00:00 2001 From: lgunreddi Date: Thu, 2 Jul 2026 15:22:48 -0400 Subject: [PATCH 16/41] Update docs.json --- docs.json | 175 +++++++++++++++++++++++++++--------------------------- 1 file changed, 89 insertions(+), 86 deletions(-) diff --git a/docs.json b/docs.json index 30b964fc..687215b6 100644 --- a/docs.json +++ b/docs.json @@ -519,92 +519,95 @@ "pages": [ "api-reference-v2/overview" ] - }, - { - "group": "Pods", - "openapi": "api-reference-v2/openapi.json", - "pages": [ - "GET /v2/pods", - "POST /v2/pods", - "GET /v2/pods/{id}", - "PATCH /v2/pods/{id}", - "DELETE /v2/pods/{id}", - "POST /v2/pods/{id}/action" - ] - }, - { - "group": "Serverless", - "openapi": "api-reference-v2/openapi.json", - "pages": [ - "GET /v2/serverless", - "POST /v2/serverless", - "GET /v2/serverless/{id}", - "PATCH /v2/serverless/{id}", - "DELETE /v2/serverless/{id}", - "GET /v2/serverless/{id}/workers" - ] - }, - { - "group": "Templates", - "openapi": "api-reference-v2/openapi.json", - "pages": [ - "GET /v2/templates", - "POST /v2/templates", - "GET /v2/templates/{id}", - "PATCH /v2/templates/{id}", - "DELETE /v2/templates/{id}" - ] - }, - { - "group": "Network Volumes", - "openapi": "api-reference-v2/openapi.json", - "pages": [ - "GET /v2/networkvolumes", - "POST /v2/networkvolumes", - "GET /v2/networkvolumes/{id}", - "PATCH /v2/networkvolumes/{id}", - "DELETE /v2/networkvolumes/{id}" - ] - }, - { - "group": "Tags", - "openapi": "api-reference-v2/openapi.json", - "pages": [ - "GET /v2/tags", - "POST /v2/tags", - "GET /v2/tags/{id}", - "PATCH /v2/tags/{id}", - "DELETE /v2/tags/{id}", - "PUT /v2/tags/{id}/resources/{resourceType}/{resourceId}", - "DELETE /v2/tags/{id}/resources/{resourceType}/{resourceId}" - ] - }, - { - "group": "Container Registry Auths", - "openapi": "api-reference-v2/openapi.json", - "pages": [ - "GET /v2/containerregistryauth", - "POST /v2/containerregistryauth", - "GET /v2/containerregistryauth/{id}", - "DELETE /v2/containerregistryauth/{id}" - ] - }, - { - "group": "Catalog", - "openapi": "api-reference-v2/openapi.json", - "pages": [ - "GET /v2/catalog/gpus", - "GET /v2/catalog/cpus", - "GET /v2/catalog/datacenters" - ] - }, - { - "group": "Billing", - "openapi": "api-reference-v2/openapi.json", - "pages": [ - "GET /v2/billing" - ] - } + }, + { + "group": "Pods", + "pages": [ + "api-reference-v2/pods/list-pods", + "api-reference-v2/pods/create-a-pod", + "api-reference-v2/pods/get-a-pod", + "api-reference-v2/pods/terminate-a-pod", + "api-reference-v2/pods/update-a-pod", + "api-reference-v2/pods/stream-pod-logs", + "api-reference-v2/pods/trigger-a-pod-state-transition" + ] + }, + { + "group": "Serverless", + "pages": [ + "api-reference-v2/serverless/list-serverless-endpoints", + "api-reference-v2/serverless/create-a-serverless-endpoint", + "api-reference-v2/serverless/get-a-serverless-endpoint", + "api-reference-v2/serverless/delete-a-serverless-endpoint", + "api-reference-v2/serverless/update-a-serverless-endpoint", + "api-reference-v2/serverless/list-serverless-endpoint-workers", + "api-reference-v2/serverless/list-serverless-endpoint-releases", + "api-reference-v2/serverless/stream-serverless-worker-logs" + ] + }, + { + "group": "Templates", + "pages": [ + "api-reference-v2/templates/list-templates", + "api-reference-v2/templates/create-a-template", + "api-reference-v2/templates/get-a-template", + "api-reference-v2/templates/delete-a-template", + "api-reference-v2/templates/update-a-template" + ] + }, + { + "group": "Tags", + "pages": [ + "api-reference-v2/tags/list-tags", + "api-reference-v2/tags/create-a-tag", + "api-reference-v2/tags/get-a-tag", + "api-reference-v2/tags/delete-a-tag", + "api-reference-v2/tags/update-a-tag", + "api-reference-v2/tags/attach-a-resource-to-a-tag", + "api-reference-v2/tags/detach-a-resource-from-a-tag" + ] + }, + { + "group": "Network Volumes", + "pages": [ + "api-reference-v2/network-volumes/list-network-volumes", + "api-reference-v2/network-volumes/create-a-network-volume", + "api-reference-v2/network-volumes/get-a-network-volume", + "api-reference-v2/network-volumes/delete-a-network-volume", + "api-reference-v2/network-volumes/update-a-network-volume" + ] + }, + { + "group": "Registries", + "pages": [ + "api-reference-v2/registries/list-container-registries", + "api-reference-v2/registries/create-a-container-registry-credential", + "api-reference-v2/registries/get-a-container-registry-credential", + "api-reference-v2/registries/delete-a-container-registry-credential" + ] + }, + { + "group": "Catalog", + "pages": [ + "api-reference-v2/catalog/list-gpu-types", + "api-reference-v2/catalog/get-a-gpu-type", + "api-reference-v2/catalog/list-cpu-types", + "api-reference-v2/catalog/get-a-cpu-type", + "api-reference-v2/catalog/list-data-centers", + "api-reference-v2/catalog/get-a-data-center" + ] + }, + { + "group": "Billing", + "pages": [ + "api-reference-v2/billing/get-aggregated-billing-history", + "api-reference-v2/billing/get-pod-billing-history", + "api-reference-v2/billing/get-serverless-billing-history", + "api-reference-v2/billing/get-public-endpoint-billing-history", + "api-reference-v2/billing/get-network-volume-billing-history", + "api-reference-v2/billing/get-instant-cluster-billing-history" + ] + } ] }, { From 325662b1e2963910a7d9030631c03e70eefbc178 Mon Sep 17 00:00:00 2001 From: Lavanya Gunreddi Date: Thu, 2 Jul 2026 15:25:54 -0400 Subject: [PATCH 17/41] Regenerate v2 API reference pages from openapi.json --- api-reference-v2/billing/get-aggregated-billing-history.mdx | 3 +++ .../billing/get-instant-cluster-billing-history.mdx | 3 +++ .../billing/get-network-volume-billing-history.mdx | 3 +++ api-reference-v2/billing/get-pod-billing-history.mdx | 3 +++ .../billing/get-public-endpoint-billing-history.mdx | 3 +++ api-reference-v2/billing/get-serverless-billing-history.mdx | 3 +++ api-reference-v2/catalog/get-a-cpu-type.mdx | 3 +++ api-reference-v2/catalog/get-a-data-center.mdx | 3 +++ api-reference-v2/catalog/get-a-gpu-type.mdx | 3 +++ api-reference-v2/catalog/list-cpu-types.mdx | 3 +++ api-reference-v2/catalog/list-data-centers.mdx | 3 +++ api-reference-v2/catalog/list-gpu-types.mdx | 3 +++ api-reference-v2/network-volumes/create-a-network-volume.mdx | 3 +++ api-reference-v2/network-volumes/delete-a-network-volume.mdx | 3 +++ api-reference-v2/network-volumes/get-a-network-volume.mdx | 3 +++ api-reference-v2/network-volumes/list-network-volumes.mdx | 3 +++ api-reference-v2/network-volumes/update-a-network-volume.mdx | 3 +++ api-reference-v2/pods/create-a-pod.mdx | 3 +++ api-reference-v2/pods/get-a-pod.mdx | 3 +++ api-reference-v2/pods/list-pods.mdx | 3 +++ api-reference-v2/pods/stream-pod-logs.mdx | 3 +++ api-reference-v2/pods/terminate-a-pod.mdx | 3 +++ api-reference-v2/pods/trigger-a-pod-state-transition.mdx | 3 +++ api-reference-v2/pods/update-a-pod.mdx | 3 +++ .../registries/create-a-container-registry-credential.mdx | 3 +++ .../registries/delete-a-container-registry-credential.mdx | 3 +++ .../registries/get-a-container-registry-credential.mdx | 3 +++ api-reference-v2/registries/list-container-registries.mdx | 3 +++ api-reference-v2/serverless/create-a-serverless-endpoint.mdx | 3 +++ api-reference-v2/serverless/delete-a-serverless-endpoint.mdx | 3 +++ api-reference-v2/serverless/get-a-serverless-endpoint.mdx | 3 +++ .../serverless/list-serverless-endpoint-releases.mdx | 3 +++ .../serverless/list-serverless-endpoint-workers.mdx | 3 +++ api-reference-v2/serverless/list-serverless-endpoints.mdx | 3 +++ api-reference-v2/serverless/stream-serverless-worker-logs.mdx | 3 +++ api-reference-v2/serverless/update-a-serverless-endpoint.mdx | 3 +++ api-reference-v2/tags/attach-a-resource-to-a-tag.mdx | 3 +++ api-reference-v2/tags/create-a-tag.mdx | 3 +++ api-reference-v2/tags/delete-a-tag.mdx | 3 +++ api-reference-v2/tags/detach-a-resource-from-a-tag.mdx | 3 +++ api-reference-v2/tags/get-a-tag.mdx | 3 +++ api-reference-v2/tags/list-tags.mdx | 3 +++ api-reference-v2/tags/update-a-tag.mdx | 3 +++ api-reference-v2/templates/create-a-template.mdx | 3 +++ api-reference-v2/templates/delete-a-template.mdx | 3 +++ api-reference-v2/templates/get-a-template.mdx | 3 +++ api-reference-v2/templates/list-templates.mdx | 3 +++ api-reference-v2/templates/update-a-template.mdx | 3 +++ 48 files changed, 144 insertions(+) create mode 100644 api-reference-v2/billing/get-aggregated-billing-history.mdx create mode 100644 api-reference-v2/billing/get-instant-cluster-billing-history.mdx create mode 100644 api-reference-v2/billing/get-network-volume-billing-history.mdx create mode 100644 api-reference-v2/billing/get-pod-billing-history.mdx create mode 100644 api-reference-v2/billing/get-public-endpoint-billing-history.mdx create mode 100644 api-reference-v2/billing/get-serverless-billing-history.mdx create mode 100644 api-reference-v2/catalog/get-a-cpu-type.mdx create mode 100644 api-reference-v2/catalog/get-a-data-center.mdx create mode 100644 api-reference-v2/catalog/get-a-gpu-type.mdx create mode 100644 api-reference-v2/catalog/list-cpu-types.mdx create mode 100644 api-reference-v2/catalog/list-data-centers.mdx create mode 100644 api-reference-v2/catalog/list-gpu-types.mdx create mode 100644 api-reference-v2/network-volumes/create-a-network-volume.mdx create mode 100644 api-reference-v2/network-volumes/delete-a-network-volume.mdx create mode 100644 api-reference-v2/network-volumes/get-a-network-volume.mdx create mode 100644 api-reference-v2/network-volumes/list-network-volumes.mdx create mode 100644 api-reference-v2/network-volumes/update-a-network-volume.mdx create mode 100644 api-reference-v2/pods/create-a-pod.mdx create mode 100644 api-reference-v2/pods/get-a-pod.mdx create mode 100644 api-reference-v2/pods/list-pods.mdx create mode 100644 api-reference-v2/pods/stream-pod-logs.mdx create mode 100644 api-reference-v2/pods/terminate-a-pod.mdx create mode 100644 api-reference-v2/pods/trigger-a-pod-state-transition.mdx create mode 100644 api-reference-v2/pods/update-a-pod.mdx create mode 100644 api-reference-v2/registries/create-a-container-registry-credential.mdx create mode 100644 api-reference-v2/registries/delete-a-container-registry-credential.mdx create mode 100644 api-reference-v2/registries/get-a-container-registry-credential.mdx create mode 100644 api-reference-v2/registries/list-container-registries.mdx create mode 100644 api-reference-v2/serverless/create-a-serverless-endpoint.mdx create mode 100644 api-reference-v2/serverless/delete-a-serverless-endpoint.mdx create mode 100644 api-reference-v2/serverless/get-a-serverless-endpoint.mdx create mode 100644 api-reference-v2/serverless/list-serverless-endpoint-releases.mdx create mode 100644 api-reference-v2/serverless/list-serverless-endpoint-workers.mdx create mode 100644 api-reference-v2/serverless/list-serverless-endpoints.mdx create mode 100644 api-reference-v2/serverless/stream-serverless-worker-logs.mdx create mode 100644 api-reference-v2/serverless/update-a-serverless-endpoint.mdx create mode 100644 api-reference-v2/tags/attach-a-resource-to-a-tag.mdx create mode 100644 api-reference-v2/tags/create-a-tag.mdx create mode 100644 api-reference-v2/tags/delete-a-tag.mdx create mode 100644 api-reference-v2/tags/detach-a-resource-from-a-tag.mdx create mode 100644 api-reference-v2/tags/get-a-tag.mdx create mode 100644 api-reference-v2/tags/list-tags.mdx create mode 100644 api-reference-v2/tags/update-a-tag.mdx create mode 100644 api-reference-v2/templates/create-a-template.mdx create mode 100644 api-reference-v2/templates/delete-a-template.mdx create mode 100644 api-reference-v2/templates/get-a-template.mdx create mode 100644 api-reference-v2/templates/list-templates.mdx create mode 100644 api-reference-v2/templates/update-a-template.mdx diff --git a/api-reference-v2/billing/get-aggregated-billing-history.mdx b/api-reference-v2/billing/get-aggregated-billing-history.mdx new file mode 100644 index 00000000..bcd31c8a --- /dev/null +++ b/api-reference-v2/billing/get-aggregated-billing-history.mdx @@ -0,0 +1,3 @@ +--- +openapi: get /v2/billing +--- \ No newline at end of file diff --git a/api-reference-v2/billing/get-instant-cluster-billing-history.mdx b/api-reference-v2/billing/get-instant-cluster-billing-history.mdx new file mode 100644 index 00000000..698a90ee --- /dev/null +++ b/api-reference-v2/billing/get-instant-cluster-billing-history.mdx @@ -0,0 +1,3 @@ +--- +openapi: get /v2/billing/clusters +--- \ No newline at end of file diff --git a/api-reference-v2/billing/get-network-volume-billing-history.mdx b/api-reference-v2/billing/get-network-volume-billing-history.mdx new file mode 100644 index 00000000..d86124d5 --- /dev/null +++ b/api-reference-v2/billing/get-network-volume-billing-history.mdx @@ -0,0 +1,3 @@ +--- +openapi: get /v2/billing/networkvolumes +--- \ No newline at end of file diff --git a/api-reference-v2/billing/get-pod-billing-history.mdx b/api-reference-v2/billing/get-pod-billing-history.mdx new file mode 100644 index 00000000..9bdf6f98 --- /dev/null +++ b/api-reference-v2/billing/get-pod-billing-history.mdx @@ -0,0 +1,3 @@ +--- +openapi: get /v2/billing/pods +--- \ No newline at end of file diff --git a/api-reference-v2/billing/get-public-endpoint-billing-history.mdx b/api-reference-v2/billing/get-public-endpoint-billing-history.mdx new file mode 100644 index 00000000..3c595472 --- /dev/null +++ b/api-reference-v2/billing/get-public-endpoint-billing-history.mdx @@ -0,0 +1,3 @@ +--- +openapi: get /v2/billing/endpoints +--- \ No newline at end of file diff --git a/api-reference-v2/billing/get-serverless-billing-history.mdx b/api-reference-v2/billing/get-serverless-billing-history.mdx new file mode 100644 index 00000000..a9e522ff --- /dev/null +++ b/api-reference-v2/billing/get-serverless-billing-history.mdx @@ -0,0 +1,3 @@ +--- +openapi: get /v2/billing/serverless +--- \ No newline at end of file diff --git a/api-reference-v2/catalog/get-a-cpu-type.mdx b/api-reference-v2/catalog/get-a-cpu-type.mdx new file mode 100644 index 00000000..8774bb0b --- /dev/null +++ b/api-reference-v2/catalog/get-a-cpu-type.mdx @@ -0,0 +1,3 @@ +--- +openapi: get /v2/catalog/cpus/{id} +--- \ No newline at end of file diff --git a/api-reference-v2/catalog/get-a-data-center.mdx b/api-reference-v2/catalog/get-a-data-center.mdx new file mode 100644 index 00000000..c1257ed6 --- /dev/null +++ b/api-reference-v2/catalog/get-a-data-center.mdx @@ -0,0 +1,3 @@ +--- +openapi: get /v2/catalog/datacenters/{id} +--- \ No newline at end of file diff --git a/api-reference-v2/catalog/get-a-gpu-type.mdx b/api-reference-v2/catalog/get-a-gpu-type.mdx new file mode 100644 index 00000000..ee108f6d --- /dev/null +++ b/api-reference-v2/catalog/get-a-gpu-type.mdx @@ -0,0 +1,3 @@ +--- +openapi: get /v2/catalog/gpus/{id} +--- \ No newline at end of file diff --git a/api-reference-v2/catalog/list-cpu-types.mdx b/api-reference-v2/catalog/list-cpu-types.mdx new file mode 100644 index 00000000..d9a9c572 --- /dev/null +++ b/api-reference-v2/catalog/list-cpu-types.mdx @@ -0,0 +1,3 @@ +--- +openapi: get /v2/catalog/cpus +--- \ No newline at end of file diff --git a/api-reference-v2/catalog/list-data-centers.mdx b/api-reference-v2/catalog/list-data-centers.mdx new file mode 100644 index 00000000..5afde303 --- /dev/null +++ b/api-reference-v2/catalog/list-data-centers.mdx @@ -0,0 +1,3 @@ +--- +openapi: get /v2/catalog/datacenters +--- \ No newline at end of file diff --git a/api-reference-v2/catalog/list-gpu-types.mdx b/api-reference-v2/catalog/list-gpu-types.mdx new file mode 100644 index 00000000..fbbd3bc4 --- /dev/null +++ b/api-reference-v2/catalog/list-gpu-types.mdx @@ -0,0 +1,3 @@ +--- +openapi: get /v2/catalog/gpus +--- \ No newline at end of file diff --git a/api-reference-v2/network-volumes/create-a-network-volume.mdx b/api-reference-v2/network-volumes/create-a-network-volume.mdx new file mode 100644 index 00000000..27ddf2d3 --- /dev/null +++ b/api-reference-v2/network-volumes/create-a-network-volume.mdx @@ -0,0 +1,3 @@ +--- +openapi: post /v2/network-volumes +--- \ No newline at end of file diff --git a/api-reference-v2/network-volumes/delete-a-network-volume.mdx b/api-reference-v2/network-volumes/delete-a-network-volume.mdx new file mode 100644 index 00000000..21f2511e --- /dev/null +++ b/api-reference-v2/network-volumes/delete-a-network-volume.mdx @@ -0,0 +1,3 @@ +--- +openapi: delete /v2/network-volumes/{id} +--- \ No newline at end of file diff --git a/api-reference-v2/network-volumes/get-a-network-volume.mdx b/api-reference-v2/network-volumes/get-a-network-volume.mdx new file mode 100644 index 00000000..496f3469 --- /dev/null +++ b/api-reference-v2/network-volumes/get-a-network-volume.mdx @@ -0,0 +1,3 @@ +--- +openapi: get /v2/network-volumes/{id} +--- \ No newline at end of file diff --git a/api-reference-v2/network-volumes/list-network-volumes.mdx b/api-reference-v2/network-volumes/list-network-volumes.mdx new file mode 100644 index 00000000..23757b88 --- /dev/null +++ b/api-reference-v2/network-volumes/list-network-volumes.mdx @@ -0,0 +1,3 @@ +--- +openapi: get /v2/network-volumes +--- \ No newline at end of file diff --git a/api-reference-v2/network-volumes/update-a-network-volume.mdx b/api-reference-v2/network-volumes/update-a-network-volume.mdx new file mode 100644 index 00000000..d187efee --- /dev/null +++ b/api-reference-v2/network-volumes/update-a-network-volume.mdx @@ -0,0 +1,3 @@ +--- +openapi: patch /v2/network-volumes/{id} +--- \ No newline at end of file diff --git a/api-reference-v2/pods/create-a-pod.mdx b/api-reference-v2/pods/create-a-pod.mdx new file mode 100644 index 00000000..158e202c --- /dev/null +++ b/api-reference-v2/pods/create-a-pod.mdx @@ -0,0 +1,3 @@ +--- +openapi: post /v2/pods +--- \ No newline at end of file diff --git a/api-reference-v2/pods/get-a-pod.mdx b/api-reference-v2/pods/get-a-pod.mdx new file mode 100644 index 00000000..c7905c69 --- /dev/null +++ b/api-reference-v2/pods/get-a-pod.mdx @@ -0,0 +1,3 @@ +--- +openapi: get /v2/pods/{id} +--- \ No newline at end of file diff --git a/api-reference-v2/pods/list-pods.mdx b/api-reference-v2/pods/list-pods.mdx new file mode 100644 index 00000000..e60e3254 --- /dev/null +++ b/api-reference-v2/pods/list-pods.mdx @@ -0,0 +1,3 @@ +--- +openapi: get /v2/pods +--- \ No newline at end of file diff --git a/api-reference-v2/pods/stream-pod-logs.mdx b/api-reference-v2/pods/stream-pod-logs.mdx new file mode 100644 index 00000000..51e02d22 --- /dev/null +++ b/api-reference-v2/pods/stream-pod-logs.mdx @@ -0,0 +1,3 @@ +--- +openapi: get /v2/pods/{id}/logs +--- \ No newline at end of file diff --git a/api-reference-v2/pods/terminate-a-pod.mdx b/api-reference-v2/pods/terminate-a-pod.mdx new file mode 100644 index 00000000..fd09c1e0 --- /dev/null +++ b/api-reference-v2/pods/terminate-a-pod.mdx @@ -0,0 +1,3 @@ +--- +openapi: delete /v2/pods/{id} +--- \ No newline at end of file diff --git a/api-reference-v2/pods/trigger-a-pod-state-transition.mdx b/api-reference-v2/pods/trigger-a-pod-state-transition.mdx new file mode 100644 index 00000000..64b1adab --- /dev/null +++ b/api-reference-v2/pods/trigger-a-pod-state-transition.mdx @@ -0,0 +1,3 @@ +--- +openapi: post /v2/pods/{id}/action +--- \ No newline at end of file diff --git a/api-reference-v2/pods/update-a-pod.mdx b/api-reference-v2/pods/update-a-pod.mdx new file mode 100644 index 00000000..f61bf090 --- /dev/null +++ b/api-reference-v2/pods/update-a-pod.mdx @@ -0,0 +1,3 @@ +--- +openapi: patch /v2/pods/{id} +--- \ No newline at end of file diff --git a/api-reference-v2/registries/create-a-container-registry-credential.mdx b/api-reference-v2/registries/create-a-container-registry-credential.mdx new file mode 100644 index 00000000..7616eac1 --- /dev/null +++ b/api-reference-v2/registries/create-a-container-registry-credential.mdx @@ -0,0 +1,3 @@ +--- +openapi: post /v2/registries +--- \ No newline at end of file diff --git a/api-reference-v2/registries/delete-a-container-registry-credential.mdx b/api-reference-v2/registries/delete-a-container-registry-credential.mdx new file mode 100644 index 00000000..985acddc --- /dev/null +++ b/api-reference-v2/registries/delete-a-container-registry-credential.mdx @@ -0,0 +1,3 @@ +--- +openapi: delete /v2/registries/{id} +--- \ No newline at end of file diff --git a/api-reference-v2/registries/get-a-container-registry-credential.mdx b/api-reference-v2/registries/get-a-container-registry-credential.mdx new file mode 100644 index 00000000..cee62e34 --- /dev/null +++ b/api-reference-v2/registries/get-a-container-registry-credential.mdx @@ -0,0 +1,3 @@ +--- +openapi: get /v2/registries/{id} +--- \ No newline at end of file diff --git a/api-reference-v2/registries/list-container-registries.mdx b/api-reference-v2/registries/list-container-registries.mdx new file mode 100644 index 00000000..8788754c --- /dev/null +++ b/api-reference-v2/registries/list-container-registries.mdx @@ -0,0 +1,3 @@ +--- +openapi: get /v2/registries +--- \ No newline at end of file diff --git a/api-reference-v2/serverless/create-a-serverless-endpoint.mdx b/api-reference-v2/serverless/create-a-serverless-endpoint.mdx new file mode 100644 index 00000000..02946a00 --- /dev/null +++ b/api-reference-v2/serverless/create-a-serverless-endpoint.mdx @@ -0,0 +1,3 @@ +--- +openapi: post /v2/serverless +--- \ No newline at end of file diff --git a/api-reference-v2/serverless/delete-a-serverless-endpoint.mdx b/api-reference-v2/serverless/delete-a-serverless-endpoint.mdx new file mode 100644 index 00000000..8ab810d0 --- /dev/null +++ b/api-reference-v2/serverless/delete-a-serverless-endpoint.mdx @@ -0,0 +1,3 @@ +--- +openapi: delete /v2/serverless/{id} +--- \ No newline at end of file diff --git a/api-reference-v2/serverless/get-a-serverless-endpoint.mdx b/api-reference-v2/serverless/get-a-serverless-endpoint.mdx new file mode 100644 index 00000000..fea19782 --- /dev/null +++ b/api-reference-v2/serverless/get-a-serverless-endpoint.mdx @@ -0,0 +1,3 @@ +--- +openapi: get /v2/serverless/{id} +--- \ No newline at end of file diff --git a/api-reference-v2/serverless/list-serverless-endpoint-releases.mdx b/api-reference-v2/serverless/list-serverless-endpoint-releases.mdx new file mode 100644 index 00000000..47da7f10 --- /dev/null +++ b/api-reference-v2/serverless/list-serverless-endpoint-releases.mdx @@ -0,0 +1,3 @@ +--- +openapi: get /v2/serverless/{id}/releases +--- \ No newline at end of file diff --git a/api-reference-v2/serverless/list-serverless-endpoint-workers.mdx b/api-reference-v2/serverless/list-serverless-endpoint-workers.mdx new file mode 100644 index 00000000..5c856815 --- /dev/null +++ b/api-reference-v2/serverless/list-serverless-endpoint-workers.mdx @@ -0,0 +1,3 @@ +--- +openapi: get /v2/serverless/{id}/workers +--- \ No newline at end of file diff --git a/api-reference-v2/serverless/list-serverless-endpoints.mdx b/api-reference-v2/serverless/list-serverless-endpoints.mdx new file mode 100644 index 00000000..1df51289 --- /dev/null +++ b/api-reference-v2/serverless/list-serverless-endpoints.mdx @@ -0,0 +1,3 @@ +--- +openapi: get /v2/serverless +--- \ No newline at end of file diff --git a/api-reference-v2/serverless/stream-serverless-worker-logs.mdx b/api-reference-v2/serverless/stream-serverless-worker-logs.mdx new file mode 100644 index 00000000..50f26d99 --- /dev/null +++ b/api-reference-v2/serverless/stream-serverless-worker-logs.mdx @@ -0,0 +1,3 @@ +--- +openapi: get /v2/serverless/{id}/workers/{workerId}/logs +--- \ No newline at end of file diff --git a/api-reference-v2/serverless/update-a-serverless-endpoint.mdx b/api-reference-v2/serverless/update-a-serverless-endpoint.mdx new file mode 100644 index 00000000..ef550a64 --- /dev/null +++ b/api-reference-v2/serverless/update-a-serverless-endpoint.mdx @@ -0,0 +1,3 @@ +--- +openapi: patch /v2/serverless/{id} +--- \ No newline at end of file diff --git a/api-reference-v2/tags/attach-a-resource-to-a-tag.mdx b/api-reference-v2/tags/attach-a-resource-to-a-tag.mdx new file mode 100644 index 00000000..3c211d82 --- /dev/null +++ b/api-reference-v2/tags/attach-a-resource-to-a-tag.mdx @@ -0,0 +1,3 @@ +--- +openapi: put /v2/tags/{id}/resources/{resourceType}/{resourceId} +--- \ No newline at end of file diff --git a/api-reference-v2/tags/create-a-tag.mdx b/api-reference-v2/tags/create-a-tag.mdx new file mode 100644 index 00000000..d9f37c8d --- /dev/null +++ b/api-reference-v2/tags/create-a-tag.mdx @@ -0,0 +1,3 @@ +--- +openapi: post /v2/tags +--- \ No newline at end of file diff --git a/api-reference-v2/tags/delete-a-tag.mdx b/api-reference-v2/tags/delete-a-tag.mdx new file mode 100644 index 00000000..88ec5e8b --- /dev/null +++ b/api-reference-v2/tags/delete-a-tag.mdx @@ -0,0 +1,3 @@ +--- +openapi: delete /v2/tags/{id} +--- \ No newline at end of file diff --git a/api-reference-v2/tags/detach-a-resource-from-a-tag.mdx b/api-reference-v2/tags/detach-a-resource-from-a-tag.mdx new file mode 100644 index 00000000..cd42ab52 --- /dev/null +++ b/api-reference-v2/tags/detach-a-resource-from-a-tag.mdx @@ -0,0 +1,3 @@ +--- +openapi: delete /v2/tags/{id}/resources/{resourceType}/{resourceId} +--- \ No newline at end of file diff --git a/api-reference-v2/tags/get-a-tag.mdx b/api-reference-v2/tags/get-a-tag.mdx new file mode 100644 index 00000000..3f425172 --- /dev/null +++ b/api-reference-v2/tags/get-a-tag.mdx @@ -0,0 +1,3 @@ +--- +openapi: get /v2/tags/{id} +--- \ No newline at end of file diff --git a/api-reference-v2/tags/list-tags.mdx b/api-reference-v2/tags/list-tags.mdx new file mode 100644 index 00000000..ef9d3372 --- /dev/null +++ b/api-reference-v2/tags/list-tags.mdx @@ -0,0 +1,3 @@ +--- +openapi: get /v2/tags +--- \ No newline at end of file diff --git a/api-reference-v2/tags/update-a-tag.mdx b/api-reference-v2/tags/update-a-tag.mdx new file mode 100644 index 00000000..37e77865 --- /dev/null +++ b/api-reference-v2/tags/update-a-tag.mdx @@ -0,0 +1,3 @@ +--- +openapi: patch /v2/tags/{id} +--- \ No newline at end of file diff --git a/api-reference-v2/templates/create-a-template.mdx b/api-reference-v2/templates/create-a-template.mdx new file mode 100644 index 00000000..0d70acd1 --- /dev/null +++ b/api-reference-v2/templates/create-a-template.mdx @@ -0,0 +1,3 @@ +--- +openapi: post /v2/templates +--- \ No newline at end of file diff --git a/api-reference-v2/templates/delete-a-template.mdx b/api-reference-v2/templates/delete-a-template.mdx new file mode 100644 index 00000000..1ee1a748 --- /dev/null +++ b/api-reference-v2/templates/delete-a-template.mdx @@ -0,0 +1,3 @@ +--- +openapi: delete /v2/templates/{id} +--- \ No newline at end of file diff --git a/api-reference-v2/templates/get-a-template.mdx b/api-reference-v2/templates/get-a-template.mdx new file mode 100644 index 00000000..89dfe8f1 --- /dev/null +++ b/api-reference-v2/templates/get-a-template.mdx @@ -0,0 +1,3 @@ +--- +openapi: get /v2/templates/{id} +--- \ No newline at end of file diff --git a/api-reference-v2/templates/list-templates.mdx b/api-reference-v2/templates/list-templates.mdx new file mode 100644 index 00000000..14a9fae3 --- /dev/null +++ b/api-reference-v2/templates/list-templates.mdx @@ -0,0 +1,3 @@ +--- +openapi: get /v2/templates +--- \ No newline at end of file diff --git a/api-reference-v2/templates/update-a-template.mdx b/api-reference-v2/templates/update-a-template.mdx new file mode 100644 index 00000000..9602bb4e --- /dev/null +++ b/api-reference-v2/templates/update-a-template.mdx @@ -0,0 +1,3 @@ +--- +openapi: patch /v2/templates/{id} +--- \ No newline at end of file From 551a28080c2643129ea4d01f8a805e21b10a5569 Mon Sep 17 00:00:00 2001 From: lgunreddi Date: Wed, 15 Jul 2026 13:25:24 -0400 Subject: [PATCH 18/41] Update overview.mdx --- api-reference-v2/overview.mdx | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/api-reference-v2/overview.mdx b/api-reference-v2/overview.mdx index 0a355342..a7d2b38e 100644 --- a/api-reference-v2/overview.mdx +++ b/api-reference-v2/overview.mdx @@ -20,10 +20,12 @@ The Runpod REST API provides programmatic access to all Runpod compute resources ## Available resources - **Pods**: Create and manage persistent GPU instances for development, training, and long-running workloads. -- **Serverless endpoints**: Deploy and scale containerized applications with autoscaling and job monitoring. -- **Network volumes**: Create persistent storage attachable to multiple resources. +- **Serverless**: Deploy and scale containerized applications with autoscaling and job monitoring. - **Templates**: Save and reuse Pod and endpoint configurations. +- **Tags**: Create and manage tags, and attach or detach them from resources. +- **Network volumes**: Create persistent storage attachable to multiple resources. - **Container registry auth**: Connect to private Docker registries. +- **Catalog**: Browse available GPU types, CPU types, and data centers. - **Billing**: Access usage metrics and billing information. ## Authentication From 06cd179fd13845c3ba4c7da36cac541c17f347f8 Mon Sep 17 00:00:00 2001 From: lgunreddi Date: Mon, 20 Jul 2026 15:36:47 -0400 Subject: [PATCH 19/41] Update overview.mdx From 27f2facd3974c9f7b7e08f4d92cb6afe5546cb55 Mon Sep 17 00:00:00 2001 From: lgunreddi Date: Mon, 20 Jul 2026 15:48:03 -0400 Subject: [PATCH 20/41] Update openapi.json --- api-reference-v2/openapi.json | 3596 ++++++++++++++++++++++++--------- 1 file changed, 2666 insertions(+), 930 deletions(-) diff --git a/api-reference-v2/openapi.json b/api-reference-v2/openapi.json index f3a4c735..d7b026ff 100644 --- a/api-reference-v2/openapi.json +++ b/api-reference-v2/openapi.json @@ -1,14 +1,14 @@ { - "openapi": "3.0.3", + "openapi": "3.1.0", "info": { - "title": "RunPod REST API", + "title": "Runpod REST API", "version": "2.0.0", - "description": "RunPod public REST API — v2" + "description": "Runpod public REST API — v2" }, "servers": [ { - "url": "/", - "description": "Current server" + "url": "https://api.runpod.io", + "description": "Runpod API v2 production server" } ], "security": [ @@ -16,12 +16,174 @@ "bearerAuth": [] } ], + "tags": [ + { + "name": "Pods", + "description": "GPU and CPU pod lifecycle, configuration, actions, and log streaming." + }, + { + "name": "Serverless", + "description": "Serverless endpoint lifecycle, worker visibility, releases, and worker log streaming." + }, + { + "name": "Templates", + "description": "Reusable pod and endpoint configuration templates." + }, + { + "name": "Network Volumes", + "description": "Persistent network storage volumes for workloads." + }, + { + "name": "Registries", + "description": "Container registry credentials used to pull private images." + }, + { + "name": "Catalog", + "description": "Available GPU, CPU, and data center catalog metadata." + }, + { + "name": "Billing", + "description": "Billing history and usage cost records across resource types." + } + ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", - "bearerFormat": "RunPod API Key" + "bearerFormat": "Runpod API Key", + "description": "Runpod API key authentication. Generate an API key in the Runpod console and send it in the `Authorization` header as `Bearer `. Keys are scoped to the permissions granted when created; requests may return `403` when a valid key lacks access to the requested resource or action.\n" + } + }, + "responses": { + "UnauthorizedError": { + "description": "Authentication failed because the bearer token is missing, malformed, expired, or invalid.", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + }, + "examples": { + "missingBearerToken": { + "summary": "Missing bearer token", + "value": { + "title": "Unauthorized", + "status": 401, + "detail": "missing bearer token" + } + } + } + } + } + }, + "ForbiddenError": { + "description": "The bearer token is valid, but it does not grant access to the requested resource or action.", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + }, + "examples": { + "insufficientAccess": { + "summary": "Insufficient access", + "value": { + "title": "Forbidden", + "status": 403, + "detail": "access denied" + } + } + } + } + } + }, + "BadRequestError": { + "description": "The request could not be processed because it is malformed or conflicts with request rules.", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + }, + "examples": { + "badRequest": { + "summary": "Bad request", + "value": { + "title": "Bad Request", + "status": 400, + "detail": "request could not be processed" + } + } + } + } + } + }, + "NotFoundError": { + "description": "The requested resource was not found or is not accessible to the caller.", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + }, + "examples": { + "notFound": { + "summary": "Resource not found", + "value": { + "title": "Not Found", + "status": 404, + "detail": "resource not found" + } + } + } + } + } + }, + "UnprocessableEntityError": { + "description": "The request body or parameters were syntactically valid but failed validation.", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + }, + "examples": { + "validationFailed": { + "summary": "Validation failed", + "value": { + "title": "Unprocessable Entity", + "status": 422, + "detail": "Request validation failed." + } + } + } + } + } + }, + "MethodNotAllowedError": { + "description": "The request method is not supported for the target path.", + "headers": { + "Allow": { + "description": "Comma-separated methods supported by the target path.", + "schema": { + "type": "string" + }, + "example": "GET, POST" + } + }, + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + }, + "examples": { + "methodNotAllowed": { + "summary": "Method not allowed", + "value": { + "title": "Method Not Allowed", + "status": 405, + "detail": "The requested method is not allowed for this path." + } + } + } + } + } } }, "parameters": { @@ -211,18 +373,24 @@ "image": { "type": "string", "description": "Docker image reference", - "example": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1" + "examples": [ + "runpod/pytorch:2.8.0-py3.11-cuda12.8.1" + ] }, "args": { "type": "string", "description": "Arguments passed to the container entrypoint", - "example": "" + "examples": [ + "" + ] }, "disk": { "type": "integer", "minimum": 1, "description": "Container disk in GB (ephemeral, wiped on restart)", - "example": 50 + "examples": [ + 50 + ] }, "ports": { "type": "array", @@ -230,9 +398,11 @@ "items": { "type": "string" }, - "example": [ - "8888/http", - "22/tcp" + "examples": [ + [ + "8888/http", + "22/tcp" + ] ] }, "env": { @@ -241,15 +411,21 @@ "type": "string" }, "description": "Environment variables as key-value pairs", - "example": { - "JUPYTER_PASSWORD": "hunter2" - } + "examples": [ + { + "JUPYTER_PASSWORD": "hunter2" + } + ] }, "registry": { - "type": "string", - "nullable": true, + "type": [ + "string", + "null" + ], "description": "Container registry credential ID (for private images)", - "example": null + "examples": [ + null + ] } } }, @@ -293,12 +469,16 @@ "type": "integer", "minimum": 10, "description": "Host-local persistent storage in GB. Upstream enforces a 10 GB floor.", - "example": 20 + "examples": [ + 20 + ] }, "path": { "type": "string", "description": "Mount path inside the container. May be changed via PATCH.", - "example": "/workspace" + "examples": [ + "/workspace" + ] } } }, @@ -314,12 +494,16 @@ "volumeId": { "type": "string", "description": "ID of an existing NetworkVolume in the same data center as the pod.", - "example": "vol_xyz" + "examples": [ + "vol_xyz" + ] }, "path": { "type": "string", "description": "Mount path inside the container. No default — must be specified explicitly.", - "example": "/runpod-volume" + "examples": [ + "/runpod-volume" + ] } } }, @@ -332,14 +516,18 @@ "id": { "type": "string", "description": "GPU type identifier", - "example": "NVIDIA GeForce RTX 4090" + "examples": [ + "NVIDIA GeForce RTX 4090" + ] }, "count": { "type": "integer", "minimum": 1, "default": 1, "description": "Number of GPUs", - "example": 1 + "examples": [ + 1 + ] } } }, @@ -353,14 +541,18 @@ "id": { "type": "string", "description": "CPU flavor identifier, as returned by GET /v2/catalog/cpus.", - "example": "cpu5c", + "examples": [ + "cpu5c" + ], "minLength": 1 }, "vcpuCount": { "type": "integer", "minimum": 2, "description": "Number of vCPUs. Must be valid for the selected CPU flavor and must be a power of two.", - "example": 4 + "examples": [ + 4 + ] } } }, @@ -369,7 +561,8 @@ { "$ref": "#/components/schemas/BaseCpuConfig" } - ] + ], + "unevaluatedProperties": false }, "CpuConfig": { "allOf": [ @@ -386,7 +579,9 @@ "type": "integer", "minimum": 1, "description": "Memory allocated to the pod in GB.", - "example": 16 + "examples": [ + 16 + ] } } } @@ -409,6 +604,72 @@ "PRIORITY_FLASHBOOT" ] }, + "EndpointType": { + "type": "string", + "description": "Request-routing semantics for a modern serverless endpoint.\n- `QUEUE_BASED` — submit asynchronous or synchronous jobs through the managed queue.\n- `LOAD_BALANCING` — send requests directly to worker-defined HTTP paths.\n", + "x-enum-varnames": [ + "EndpointTypeQueueBased", + "EndpointTypeLoadBalancing" + ], + "enum": [ + "QUEUE_BASED", + "LOAD_BALANCING" + ] + }, + "QueueBasedRequestUrls": { + "type": "object", + "additionalProperties": false, + "required": [ + "run", + "runSync" + ], + "properties": { + "run": { + "type": "string", + "format": "uri", + "description": "URL for asynchronously submitting a queued job.", + "examples": [ + "https://api.runpod.ai/v2/4m7x2k9q/run" + ] + }, + "runSync": { + "type": "string", + "format": "uri", + "description": "URL for synchronously submitting a queued job.", + "examples": [ + "https://api.runpod.ai/v2/4m7x2k9q/runsync" + ] + } + } + }, + "LoadBalancingRequestUrls": { + "type": "object", + "additionalProperties": false, + "required": [ + "base" + ], + "properties": { + "base": { + "type": "string", + "format": "uri", + "description": "Base URL for worker-defined HTTP and WebSocket paths.", + "examples": [ + "https://4m7x2k9q.api.runpod.ai" + ] + } + } + }, + "EndpointRequestUrls": { + "description": "Request submission URLs appropriate to the endpoint's top-level `type`.\nQueue-based endpoints provide `run` and `runSync`; load-balancing\nendpoints provide `base` because their paths are worker-defined.\n", + "oneOf": [ + { + "$ref": "#/components/schemas/QueueBasedRequestUrls" + }, + { + "$ref": "#/components/schemas/LoadBalancingRequestUrls" + } + ] + }, "EndpointGpuConfig": { "type": "object", "required": [ @@ -422,8 +683,10 @@ "items": { "type": "string" }, - "example": [ - "ADA_24" + "examples": [ + [ + "ADA_24" + ] ] }, "count": { @@ -431,7 +694,9 @@ "minimum": 1, "default": 1, "description": "GPUs per worker", - "example": 1 + "examples": [ + 1 + ] } } }, @@ -456,26 +721,40 @@ "properties": { "id": { "type": "string", - "example": "ep_abc123" + "examples": [ + "ep_abc123" + ] }, "name": { "type": "string", - "example": "my-inference" + "examples": [ + "my-inference" + ] + }, + "type": { + "$ref": "#/components/schemas/EndpointType" + }, + "requestUrls": { + "$ref": "#/components/schemas/EndpointRequestUrls" }, "gpu": { - "nullable": true, - "allOf": [ + "anyOf": [ { "$ref": "#/components/schemas/EndpointGpuConfig" + }, + { + "type": "null" } ] }, "cpu": { - "nullable": true, "description": "Read-only. Present for CPU serverless endpoints; CPU create/update is not yet supported.", - "allOf": [ + "anyOf": [ { "$ref": "#/components/schemas/CpuConfig" + }, + { + "type": "null" } ] }, @@ -489,12 +768,16 @@ "min": { "type": "integer", "minimum": 0, - "example": 0 + "examples": [ + 0 + ] }, "max": { "type": "integer", "minimum": 0, - "example": 5 + "examples": [ + 5 + ] } } }, @@ -510,15 +793,20 @@ "$ref": "#/components/schemas/ScalerType" }, "value": { - "type": "integer", - "minimum": 1, - "example": 4 + "type": "number", + "format": "float", + "minimum": 0.5, + "examples": [ + 4 + ] }, "idleTimeout": { "type": "integer", "minimum": 0, "description": "Seconds before idle workers scale down", - "example": 5 + "examples": [ + 5 + ] } } }, @@ -527,8 +815,10 @@ "items": { "type": "string" }, - "example": [ - "US-TX-3" + "examples": [ + [ + "US-TX-3" + ] ] }, "networkVolumes": { @@ -536,14 +826,18 @@ "items": { "type": "string" }, - "example": [ - "vol_abc" + "examples": [ + [ + "vol_abc" + ] ] }, "timeout": { "type": "integer", "description": "Per-request execution timeout in milliseconds", - "example": 300000 + "examples": [ + 300000 + ] }, "flashboot": { "$ref": "#/components/schemas/FlashBoot" @@ -551,7 +845,9 @@ "createdAt": { "type": "string", "format": "date-time", - "example": "2026-03-13T20:00:00Z" + "examples": [ + "2026-03-13T20:00:00Z" + ] } } } @@ -600,7 +896,9 @@ "properties": { "id": { "type": "string", - "example": "worker_abc" + "examples": [ + "worker_abc" + ] }, "status": { "$ref": "#/components/schemas/WorkerStatus" @@ -608,51 +906,79 @@ "isStale": { "type": "boolean", "description": "True when the worker is running an older endpoint configuration than\nthe current one (e.g. mid rolling-update). This is the authoritative\nflag: it is derived from `version` vs the response's `endpointVersion`,\nexcept on legacy endpoints (`endpointVersion` 1) where it falls back\nto a container-image comparison.\n", - "example": false + "examples": [ + false + ] }, "version": { - "type": "integer", - "nullable": true, + "type": [ + "integer", + "null" + ], "description": "Endpoint configuration version this worker is running. Compare with\nthe response's `endpointVersion`. Null if unknown.\n", - "example": 4 + "examples": [ + 4 + ] }, "gpuCount": { "type": "integer", "minimum": 0, "description": "GPUs allocated to the worker.", - "example": 1 + "examples": [ + 1 + ] }, "image": { - "type": "string", - "nullable": true, + "type": [ + "string", + "null" + ], "description": "Container image the worker is running.", - "example": "my-org/sdxl-worker:latest" + "examples": [ + "my-org/sdxl-worker:latest" + ] }, "uptimeSeconds": { - "type": "integer", + "type": [ + "integer", + "null" + ], "minimum": 0, - "nullable": true, "description": "Seconds the worker has been running. Null until the worker is placed and running.", - "example": 3600 + "examples": [ + 3600 + ] }, "gpuTypeId": { - "type": "string", - "nullable": true, + "type": [ + "string", + "null" + ], "description": "GPU type the worker is placed on. Null until the worker is placed.", - "example": "NVIDIA RTX 4090" + "examples": [ + "NVIDIA RTX 4090" + ] }, "dataCenterId": { - "type": "string", - "nullable": true, + "type": [ + "string", + "null" + ], "description": "Data center the worker is placed in. Null until the worker is placed.", - "example": "US-TX-3" + "examples": [ + "US-TX-3" + ] }, "startedAt": { - "type": "string", + "type": [ + "string", + "null" + ], "format": "date-time", - "nullable": true, "description": "When the worker last started. Null if it has not started.", - "example": "2026-03-26T00:00:00Z" + "examples": [ + "2026-03-26T00:00:00Z" + ] } } }, @@ -672,37 +998,49 @@ "type": "integer", "minimum": 0, "description": "Workers actively processing a job.", - "example": 2 + "examples": [ + 2 + ] }, "idle": { "type": "integer", "minimum": 0, "description": "Ready workers polling for jobs.", - "example": 1 + "examples": [ + 1 + ] }, "initializing": { "type": "integer", "minimum": 0, "description": "Workers starting up, not yet ready.", - "example": 0 + "examples": [ + 0 + ] }, "throttled": { "type": "integer", "minimum": 0, "description": "Workers waiting on compute capacity.", - "example": 0 + "examples": [ + 0 + ] }, "unhealthy": { "type": "integer", "minimum": 0, "description": "Workers failing health checks.", - "example": 0 + "examples": [ + 0 + ] }, "total": { "type": "integer", "minimum": 0, "description": "All workers currently allocated to the endpoint.", - "example": 3 + "examples": [ + 3 + ] } } }, @@ -723,10 +1061,14 @@ "$ref": "#/components/schemas/WorkerSummary" }, "endpointVersion": { - "type": "integer", - "nullable": true, + "type": [ + "integer", + "null" + ], "description": "The endpoint's current configuration version. A worker whose\n`version` differs is running stale config (see `worker.isStale`).\nNull if unknown.\n", - "example": 4 + "examples": [ + 4 + ] } } }, @@ -753,14 +1095,14 @@ "field": { "type": "string", "description": "The changed configuration field. Top-level (e.g. `gpuCount`,\n`locations`) or template-scoped (e.g. `template.imageName`,\n`template.env`).\n", - "example": "template.imageName" + "examples": [ + "template.imageName" + ] }, "old": { - "nullable": true, "description": "Previous value, as raw JSON. Null when the field was added." }, "new": { - "nullable": true, "description": "New value, as raw JSON. Null when the field was removed." } } @@ -777,38 +1119,54 @@ "properties": { "id": { "type": "string", - "example": "rel_abc123" + "examples": [ + "rel_abc123" + ] }, "version": { - "type": "integer", - "nullable": true, + "type": [ + "integer", + "null" + ], "description": "The endpoint configuration version this release produced.", - "example": 4 + "examples": [ + 4 + ] }, "source": { "$ref": "#/components/schemas/ReleaseSource" }, "buildId": { - "type": "string", - "nullable": true, + "type": [ + "string", + "null" + ], "description": "The GitHub build that produced this release. Set when `source` is\n`GIT_BUILD`; null for `MANUAL` releases. Fetch build detail/logs via\n`/v2/serverless/{id}/builds/{buildId}`.\n", - "example": "build_abc123" + "examples": [ + "build_abc123" + ] }, "createdByUserId": { - "type": "string", - "nullable": true, + "type": [ + "string", + "null" + ], "description": "ID of the user who created the release." }, "workerCount": { "type": "integer", "minimum": 0, "description": "Workers currently running this release's version.", - "example": 2 + "examples": [ + 2 + ] }, "createdAt": { "type": "string", "format": "date-time", - "example": "2026-03-13T20:00:00Z" + "examples": [ + "2026-03-13T20:00:00Z" + ] }, "diff": { "type": "array", @@ -831,26 +1189,34 @@ "inProgress": { "type": "boolean", "description": "True while any worker is still running an older version.", - "example": true + "examples": [ + true + ] }, "workersOnLatest": { "type": "integer", "minimum": 0, "description": "Workers running the endpoint's current version.", - "example": 2 + "examples": [ + 2 + ] }, "workersTotal": { "type": "integer", "minimum": 0, "description": "All workers currently allocated to the endpoint.", - "example": 3 + "examples": [ + 3 + ] }, "percentOnLatest": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Percentage of workers on the current version (0 when there are no workers).", - "example": 67 + "examples": [ + 67 + ] } } }, @@ -862,10 +1228,14 @@ ], "properties": { "endpointVersion": { - "type": "integer", - "nullable": true, + "type": [ + "integer", + "null" + ], "description": "The endpoint's current configuration version. Null if unknown.", - "example": 4 + "examples": [ + 4 + ] }, "rollout": { "$ref": "#/components/schemas/RolloutSummary" @@ -895,13 +1265,21 @@ "name": { "type": "string", "minLength": 1, - "example": "my-inference" + "examples": [ + "my-inference" + ] }, "gpu": { - "$ref": "#/components/schemas/EndpointGpuConfig" + "allOf": [ + { + "$ref": "#/components/schemas/EndpointGpuConfig" + } + ], + "unevaluatedProperties": false }, "workers": { "type": "object", + "additionalProperties": false, "properties": { "min": { "type": "integer", @@ -917,13 +1295,15 @@ }, "scaling": { "type": "object", + "additionalProperties": false, "properties": { "type": { "$ref": "#/components/schemas/ScalerType" }, "value": { - "type": "integer", - "minimum": 1, + "type": "number", + "format": "float", + "minimum": 0.5, "default": 4 }, "idleTimeout": { @@ -960,7 +1340,8 @@ } } } - ] + ], + "unevaluatedProperties": false }, "UpdateEndpointRequest": { "allOf": [ @@ -976,10 +1357,16 @@ "minLength": 1 }, "gpu": { - "$ref": "#/components/schemas/EndpointGpuConfig" + "allOf": [ + { + "$ref": "#/components/schemas/EndpointGpuConfig" + } + ], + "unevaluatedProperties": false }, "workers": { "type": "object", + "additionalProperties": false, "properties": { "min": { "type": "integer", @@ -993,13 +1380,15 @@ }, "scaling": { "type": "object", + "additionalProperties": false, "properties": { "type": { "$ref": "#/components/schemas/ScalerType" }, "value": { - "type": "integer", - "minimum": 1 + "type": "number", + "format": "float", + "minimum": 0.5 }, "idleTimeout": { "type": "integer", @@ -1028,7 +1417,8 @@ } } } - ] + ], + "unevaluatedProperties": false }, "Utilization": { "type": "object", @@ -1036,7 +1426,9 @@ "properties": { "util": { "type": "integer", - "example": 45 + "examples": [ + 45 + ] } } }, @@ -1046,11 +1438,15 @@ "properties": { "util": { "type": "integer", - "example": 94 + "examples": [ + 94 + ] }, "memoryUtil": { "type": "integer", - "example": 78 + "examples": [ + 78 + ] } } }, @@ -1060,21 +1456,33 @@ "properties": { "private": { "type": "integer", - "example": 8888 + "examples": [ + 8888 + ] }, "public": { - "type": "integer", - "nullable": true, - "example": 43210 + "type": [ + "integer", + "null" + ], + "examples": [ + 43210 + ] }, "type": { "type": "string", - "example": "http" + "examples": [ + "http" + ] }, "ip": { - "type": "string", - "nullable": true, - "example": "45.23.12.1" + "type": [ + "string", + "null" + ], + "examples": [ + "45.23.12.1" + ] } } }, @@ -1085,7 +1493,9 @@ "uptime": { "type": "integer", "description": "Seconds since the container started", - "example": 3600 + "examples": [ + 3600 + ] }, "gpus": { "type": "array", @@ -1143,16 +1553,15 @@ }, "Cloud": { "type": "string", - "description": "Cloud tier.\n- `SECURE` — RunPod-owned datacenter hardware\n- `COMMUNITY` — community-hosted hardware\n- `ALL` — eligible for either tier (request-only; responses always\n report the concrete tier the pod was placed on)\n", + "description": "Cloud tier.\n- `SECURE` — Runpod-owned datacenter hardware\n- `COMMUNITY` — community-hosted hardware\n", "enum": [ "SECURE", - "COMMUNITY", - "ALL" + "COMMUNITY" ] }, "TemplateCategory": { "type": "string", - "description": "Hardware family this template targets.\n- `CPU` — CPU-only workloads\n- `NVIDIA` — NVIDIA GPU workloads\n- `AMD` — AMD GPU workloads\n", + "description": "Controls how the template is grouped and filtered in the Runpod console.\nIt does not affect hardware selection, scheduling, or billing.\n- `CPU` — CPU-only workloads\n- `NVIDIA` — NVIDIA GPU workloads\n- `AMD` — AMD GPU workloads\n", "enum": [ "CPU", "NVIDIA", @@ -1168,17 +1577,23 @@ "enabled": { "type": "boolean", "description": "Whether global networking is enabled, giving the pod a private IP reachable across data centers. Derived from whether the pod has an assigned global-network address.", - "example": true + "examples": [ + true + ] }, "ip": { "type": "string", "description": "The pod's assigned global-networking IP. Present only when enabled.", - "example": "10.65.1.42" + "examples": [ + "10.65.1.42" + ] }, "internalDns": { "type": "string", "description": "Internal DNS name (`.runpod.internal`), reachable from other globally-networked pods in the same account. Present only when enabled.", - "example": "gfj8b292vyg08g.runpod.internal" + "examples": [ + "gfj8b292vyg08g.runpod.internal" + ] } } }, @@ -1206,7 +1621,6 @@ "template", "cost", "locked", - "tags", "runtime", "createdAt", "startedAt", @@ -1215,11 +1629,15 @@ "properties": { "id": { "type": "string", - "example": "pod_abc123" + "examples": [ + "pod_abc123" + ] }, "name": { "type": "string", - "example": "my-training-pod" + "examples": [ + "my-training-pod" + ] }, "status": { "$ref": "#/components/schemas/PodStatus" @@ -1254,57 +1672,70 @@ "$ref": "#/components/schemas/Cloud" }, "dataCenterId": { - "type": "string", - "nullable": true, + "type": [ + "string", + "null" + ], "description": "Data center where the pod is running (assigned by scheduler)", - "example": "US-TX-3" + "examples": [ + "US-TX-3" + ] }, "template": { - "type": "string", - "nullable": true, + "type": [ + "string", + "null" + ], "description": "ID of the template this pod was created from", - "example": null + "examples": [ + null + ] }, "cost": { "type": "number", "format": "float", "description": "Current cost in USD per hour (0.0 when EXITED or TERMINATED)", - "example": 0.35 + "examples": [ + 0.35 + ] }, "locked": { "type": "boolean", "description": "Whether the pod is locked (prevents stopping or resetting)", - "example": false + "examples": [ + false + ] }, "globalNetworking": { "$ref": "#/components/schemas/PodGlobalNetworking" }, - "tags": { - "type": "array", - "description": "Tags attached to this pod.", - "items": { - "$ref": "#/components/schemas/Tag" - } - }, "runtime": { - "nullable": true, "description": "Live utilization metrics. Null when the pod is not RUNNING.", - "allOf": [ + "anyOf": [ { "$ref": "#/components/schemas/PodRuntime" + }, + { + "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", - "example": "2026-03-13T20:00:00Z" + "examples": [ + "2026-03-13T20:00:00Z" + ] }, "startedAt": { - "type": "string", + "type": [ + "string", + "null" + ], "format": "date-time", - "nullable": true, - "example": "2026-03-13T20:00:00Z" + "examples": [ + "2026-03-13T20:00:00Z" + ] } } } @@ -1326,19 +1757,32 @@ "name": { "type": "string", "minLength": 1, - "example": "my-training-pod" + "examples": [ + "my-training-pod" + ] }, "mounts": { "$ref": "#/components/schemas/Mounts" }, "gpu": { - "$ref": "#/components/schemas/GpuConfig" + "allOf": [ + { + "$ref": "#/components/schemas/GpuConfig" + } + ], + "unevaluatedProperties": false }, "cpu": { "$ref": "#/components/schemas/CreateCpuConfig" }, "cloud": { - "$ref": "#/components/schemas/Cloud" + "allOf": [ + { + "$ref": "#/components/schemas/Cloud" + } + ], + "default": "SECURE", + "description": "Cloud tier. Defaults to `SECURE` when omitted." }, "dataCenterIds": { "type": "array", @@ -1346,19 +1790,24 @@ "type": "string" }, "description": "Preferred data centers for placement. Omit or pass an empty\narray to let the scheduler choose.\n", - "example": [ - "US-TX-3" + "examples": [ + [ + "US-TX-3" + ] ] }, "globalNetworking": { "type": "boolean", "default": false, "description": "Enable global networking, giving the pod a private IP reachable across data centers. Requires an NVIDIA GPU and a global-networking-enabled data center (both enforced upstream). See `GET /v2/catalog/datacenters` (`globalNetwork`) for eligible data centers.", - "example": false + "examples": [ + false + ] } } } - ] + ], + "unevaluatedProperties": false }, "UpdatePodRequest": { "allOf": [ @@ -1385,10 +1834,12 @@ } } } - ] + ], + "unevaluatedProperties": false }, "PodActionRequest": { "type": "object", + "additionalProperties": false, "required": [ "action" ], @@ -1436,11 +1887,15 @@ "properties": { "id": { "type": "string", - "example": "tpl_abc" + "examples": [ + "tpl_abc" + ] }, "name": { "type": "string", - "example": "My PyTorch Template" + "examples": [ + "My PyTorch Template" + ] }, "mounts": { "$ref": "#/components/schemas/TemplateMounts" @@ -1448,12 +1903,16 @@ "serverless": { "type": "boolean", "description": "Whether this template is for serverless workers (true) or pods (false)", - "example": false + "examples": [ + false + ] }, "public": { "type": "boolean", - "description": "Whether this template is visible to other RunPod users", - "example": false + "description": "Whether this template is visible to other Runpod users", + "examples": [ + false + ] }, "category": { "$ref": "#/components/schemas/TemplateCategory" @@ -1471,14 +1930,15 @@ "type": "object", "required": [ "name", - "image", - "category" + "image" ], "properties": { "name": { "type": "string", "minLength": 1, - "example": "My PyTorch Template" + "examples": [ + "My PyTorch Template" + ] }, "mounts": { "$ref": "#/components/schemas/TemplateMounts" @@ -1492,11 +1952,18 @@ "default": false }, "category": { - "$ref": "#/components/schemas/TemplateCategory" + "description": "Optional. Defaults to `NVIDIA` when omitted.", + "allOf": [ + { + "$ref": "#/components/schemas/TemplateCategory" + } + ], + "default": "NVIDIA" } } } - ] + ], + "unevaluatedProperties": false }, "UpdateTemplateRequest": { "allOf": [ @@ -1524,7 +1991,8 @@ } } } - ] + ], + "unevaluatedProperties": false }, "ListTemplatesResponse": { "type": "object", @@ -1540,137 +2008,6 @@ } } }, - "TagResourceType": { - "type": "string", - "description": "Resource type attached to a tag.", - "enum": [ - "POD", - "NETWORK_VOLUME", - "CLUSTER", - "SERVERLESS_ENDPOINT" - ], - "example": "POD" - }, - "TaggedResource": { - "type": "object", - "required": [ - "id", - "type" - ], - "additionalProperties": false, - "properties": { - "id": { - "type": "string", - "description": "Resource identifier.", - "example": "pod_abc123" - }, - "type": { - "$ref": "#/components/schemas/TagResourceType" - } - } - }, - "Tag": { - "type": "object", - "required": [ - "id", - "key", - "value" - ], - "additionalProperties": false, - "properties": { - "id": { - "type": "string", - "description": "Tag identifier", - "example": "tag_abc123" - }, - "key": { - "type": "string", - "minLength": 1, - "description": "Tag key", - "example": "project" - }, - "value": { - "type": "string", - "minLength": 1, - "description": "Tag value", - "example": "gpt-training" - }, - "resources": { - "type": "array", - "description": "Populated only on direct tag responses when `?include=resources` is provided; omitted when the tag appears nested in another resource or if no resources have the tag.", - "items": { - "$ref": "#/components/schemas/TaggedResource" - } - } - } - }, - "CreateTagRequest": { - "type": "object", - "required": [ - "key", - "value" - ], - "additionalProperties": false, - "properties": { - "key": { - "type": "string", - "minLength": 1, - "example": "project" - }, - "value": { - "type": "string", - "minLength": 1, - "example": "gpt-training" - }, - "resources": { - "type": "array", - "description": "Resources to attach to the tag at create time. If any resource cannot be attached, tag creation returns an error rather than silently dropping the association.", - "items": { - "$ref": "#/components/schemas/TaggedResource" - } - } - } - }, - "UpdateTagRequest": { - "type": "object", - "minProperties": 1, - "additionalProperties": false, - "description": "At least one of `key`, `value`, or `resources` must be provided.", - "properties": { - "key": { - "type": "string", - "minLength": 1, - "example": "project" - }, - "value": { - "type": "string", - "minLength": 1, - "example": "gpt-training" - }, - "resources": { - "type": "array", - "description": "Replaces resource associations when present. Omit `resources` to leave\nexisting associations unchanged. Send `resources: []` to remove all\nassociations. Send a non-empty array to replace current associations with\nexactly those resources.\n", - "items": { - "$ref": "#/components/schemas/TaggedResource" - } - } - } - }, - "ListTagsResponse": { - "type": "object", - "required": [ - "tags" - ], - "additionalProperties": false, - "properties": { - "tags": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Tag" - } - } - } - }, "NetworkVolume": { "type": "object", "required": [ @@ -1678,31 +2015,38 @@ "name", "size", "dataCenter", - "type", - "tags" + "type" ], "properties": { "id": { "type": "string", "description": "Unique network volume identifier", - "example": "agv6w2qcg7" + "examples": [ + "agv6w2qcg7" + ] }, "name": { "type": "string", "description": "Human-readable name (not required to be unique)", - "example": "my-dataset" + "examples": [ + "my-dataset" + ] }, "size": { "type": "integer", "minimum": 10, "maximum": 4096, "description": "Allocated storage in GB", - "example": 50 + "examples": [ + 50 + ] }, "dataCenter": { "type": "string", "description": "Data center location; immutable after creation", - "example": "EU-RO-1" + "examples": [ + "EU-RO-1" + ] }, "type": { "allOf": [ @@ -1711,18 +2055,12 @@ } ], "description": "Storage tier of this volume. Set at creation and immutable." - }, - "tags": { - "type": "array", - "description": "Tags attached to this network volume.", - "items": { - "$ref": "#/components/schemas/Tag" - } } } }, "CreateNetworkVolumeRequest": { "type": "object", + "additionalProperties": false, "required": [ "name", "size", @@ -1733,20 +2071,26 @@ "type": "string", "minLength": 1, "description": "Human-readable name", - "example": "my-dataset" + "examples": [ + "my-dataset" + ] }, "size": { "type": "integer", "minimum": 10, "maximum": 4096, "description": "Storage to allocate in GB", - "example": 50 + "examples": [ + 50 + ] }, "dataCenter": { "type": "string", "minLength": 1, "description": "Data center in which to create the volume", - "example": "EU-RO-1" + "examples": [ + "EU-RO-1" + ] }, "type": { "allOf": [ @@ -1768,14 +2112,18 @@ "type": "string", "minLength": 1, "description": "New human-readable name", - "example": "renamed-volume" + "examples": [ + "renamed-volume" + ] }, "size": { "type": "integer", "minimum": 10, "maximum": 4096, "description": "New size in GB. Must be greater than or equal to the current size —\nnetwork volume storage cannot be reduced.\n", - "example": 100 + "examples": [ + 100 + ] } } }, @@ -1802,16 +2150,21 @@ "properties": { "id": { "type": "string", - "example": "reg_abc" + "examples": [ + "reg_abc" + ] }, "name": { "type": "string", - "example": "my-private-registry" + "examples": [ + "my-private-registry" + ] } } }, "CreateRegistryRequest": { "type": "object", + "additionalProperties": false, "required": [ "name", "username", @@ -1821,7 +2174,9 @@ "name": { "type": "string", "minLength": 1, - "example": "my-private-registry" + "examples": [ + "my-private-registry" + ] }, "username": { "type": "string", @@ -1849,6 +2204,141 @@ } } }, + "EcrDelegation": { + "type": "object", + "required": [ + "id", + "delegatorUserId", + "awsUser", + "repository", + "tag", + "awsRegion", + "createdAt" + ], + "properties": { + "id": { + "type": "string", + "description": "Delegation identifier", + "examples": [ + "deleg_abc123" + ] + }, + "name": { + "type": [ + "string", + "null" + ], + "description": "Optional name for the delegation", + "examples": [ + "my-delegation" + ] + }, + "delegatorUserId": { + "type": "string", + "description": "User ID that created the delegation", + "examples": [ + "user_xyz" + ] + }, + "awsUser": { + "type": "string", + "description": "AWS user/role being delegated", + "examples": [ + "123456789" + ] + }, + "repository": { + "type": "string", + "description": "ECR repository name", + "examples": [ + "runpod/deployment" + ] + }, + "tag": { + "type": "string", + "description": "ECR image tag", + "examples": [ + "latest" + ] + }, + "awsRegion": { + "type": "string", + "description": "AWS region", + "examples": [ + "us-east-2" + ] + }, + "dockerRegistryUri": { + "type": "string", + "description": "Formatted ECR registry URI for Docker login", + "examples": [ + "123456789.dkr.ecr.us-east-2.amazonaws.com" + ] + }, + "createdAt": { + "type": "string", + "format": "date-time", + "description": "When the delegation was created", + "examples": [ + "2026-03-13T20:00:00Z" + ] + } + } + }, + "CreateDelegationRequest": { + "type": "object", + "additionalProperties": false, + "required": [ + "resource" + ], + "properties": { + "resource": { + "type": "string", + "description": "ECR resource ARN", + "examples": [ + "arn:aws:ecr:us-east-2:418399314813:repository/runpod/deployment" + ] + }, + "name": { + "type": [ + "string", + "null" + ], + "description": "Optional name for the delegation", + "examples": [ + "my-delegation" + ] + } + } + }, + "ListDelegationsResponse": { + "type": "object", + "required": [ + "delegations" + ], + "properties": { + "delegations": { + "type": "array", + "items": { + "$ref": "#/components/schemas/EcrDelegation" + } + } + } + }, + "GpuManufacturer": { + "type": "string", + "description": "Canonical GPU hardware manufacturer.", + "x-enum-varnames": [ + "GpuManufacturerNVIDIA", + "GpuManufacturerAMD", + "GpuManufacturerUNKNOWN" + ], + "enum": [ + "NVIDIA", + "AMD", + "UNKNOWN" + ] + }, "GpuType": { "type": "object", "required": [ @@ -1866,36 +2356,49 @@ "id": { "type": "string", "description": "Individual GPU type identifier (use for pod creation)", - "example": "NVIDIA GeForce RTX 4090" + "examples": [ + "NVIDIA GeForce RTX 4090" + ] }, "name": { "type": "string", - "example": "RTX 4090" + "examples": [ + "RTX 4090" + ] }, "pool": { - "type": "string", - "nullable": true, + "type": [ + "string", + "null" + ], "description": "Serverless GPU pool ID (use for serverless endpoint creation). Null if GPU is not in a serverless pool.", - "example": "ADA_24" + "examples": [ + "ADA_24" + ] }, "manufacturer": { - "type": "string", - "example": "NVIDIA" + "$ref": "#/components/schemas/GpuManufacturer" }, "memory": { "type": "integer", "description": "VRAM in GB", - "example": 24 + "examples": [ + 24 + ] }, "secure": { "type": "boolean", "description": "Available on secure cloud", - "example": true + "examples": [ + true + ] }, "community": { "type": "boolean", "description": "Available on community cloud", - "example": true + "examples": [ + true + ] }, "price": { "type": "object", @@ -1907,12 +2410,16 @@ "secure": { "type": "number", "format": "float", - "example": 0.44 + "examples": [ + 0.44 + ] }, "community": { "type": "number", "format": "float", - "example": 0.31 + "examples": [ + 0.31 + ] } } }, @@ -1925,11 +2432,15 @@ "properties": { "secure": { "type": "integer", - "example": 8 + "examples": [ + 8 + ] }, "community": { "type": "integer", - "example": 4 + "examples": [ + 4 + ] } } }, @@ -2015,12 +2526,16 @@ "id": { "type": "string", "description": "Catalog resource identifier.", - "example": "NVIDIA GeForce RTX 4090" + "examples": [ + "NVIDIA GeForce RTX 4090" + ] }, "name": { "type": "string", "description": "Human-readable catalog resource name.", - "example": "RTX 4090" + "examples": [ + "RTX 4090" + ] }, "availability": { "$ref": "#/components/schemas/AvailabilityLevel" @@ -2038,12 +2553,16 @@ "id": { "type": "string", "description": "Data center identifier.", - "example": "US-CA-2" + "examples": [ + "US-CA-2" + ] }, "name": { "type": "string", "description": "Human-readable data center name.", - "example": "US California 2" + "examples": [ + "US California 2" + ] }, "availability": { "$ref": "#/components/schemas/AvailabilityLevel" @@ -2078,17 +2597,23 @@ "id": { "type": "string", "description": "CPU flavor identifier (use in cpu.id for pod creation)", - "example": "cpu5c" + "examples": [ + "cpu5c" + ] }, "name": { "type": "string", "description": "Human-readable flavor name", - "example": "Compute-Optimized" + "examples": [ + "Compute-Optimized" + ] }, "group": { "type": "string", "description": "CPU generation group", - "example": "Gen 5" + "examples": [ + "Gen 5" + ] }, "vcpu": { "type": "object", @@ -2099,11 +2624,15 @@ "properties": { "min": { "type": "integer", - "example": 2 + "examples": [ + 2 + ] }, "max": { "type": "integer", - "example": 32 + "examples": [ + 32 + ] } } }, @@ -2111,7 +2640,9 @@ "type": "number", "format": "float", "description": "GB of RAM allocated per vCPU. Multiply by the chosen vCPU\ncount (within `vcpu.min`..`vcpu.max`) to get the total RAM\nfor an instance of this flavor. May be fractional.\n", - "example": 2.5 + "examples": [ + 2.5 + ] }, "price": { "type": "object", @@ -2124,13 +2655,17 @@ "type": "number", "format": "float", "description": "Price for secure pods per vCPU. Multiply by the chosen vCPU\ncount (within `vcpu.min`..`vcpu.max`) to get the total price.\n", - "example": 0.04 + "examples": [ + 0.04 + ] }, "serverlessPerVcpu": { "type": "number", "format": "float", "description": "Price for serverless per vCPU. Multiply by the chosen vCPU\ncount (within `vcpu.min`..`vcpu.max`) to get the total price.\n", - "example": 0.03 + "examples": [ + 0.03 + ] } } }, @@ -2174,11 +2709,15 @@ "properties": { "id": { "type": "string", - "example": "US-TX-3" + "examples": [ + "US-TX-3" + ] }, "name": { "type": "string", - "example": "US Texas 3" + "examples": [ + "US Texas 3" + ] }, "region": { "$ref": "#/components/schemas/DataCenterRegion" @@ -2186,7 +2725,9 @@ "globalNetwork": { "type": "boolean", "description": "Whether this data center supports global networking (private cross-datacenter pod-to-pod network).", - "example": true + "examples": [ + true + ] }, "networkVolumeTypes": { "type": "array", @@ -2201,22 +2742,24 @@ "items": { "$ref": "#/components/schemas/Compliance" }, - "example": [ - "GDPR", - "ISO_IEC_27001", - "SOC_2_TYPE_2" + "examples": [ + [ + "GDPR", + "ISO_IEC_27001", + "SOC_2_TYPE_2" + ] ] }, "gpuAvailability": { "type": "array", - "description": "Per-GPU availability in this data center. Present only when requested with include=gpuAvailability.", + "description": "Per-GPU availability in this data center. Present only when requested with include=GPU_AVAILABILITY.", "items": { "$ref": "#/components/schemas/CatalogResourceAvailability" } }, "cpuAvailability": { "type": "array", - "description": "Per-CPU availability in this data center. Present only when requested with include=cpuAvailability.", + "description": "Per-CPU availability in this data center. Present only when requested with include=CPU_AVAILABILITY.", "items": { "$ref": "#/components/schemas/CatalogResourceAvailability" } @@ -2226,7 +2769,9 @@ "DataCenterRegion": { "type": "string", "description": "Continental region containing the data center.", - "example": "EUROPE", + "examples": [ + "EUROPE" + ], "enum": [ "NORTH_AMERICA", "SOUTH_AMERICA", @@ -2283,13 +2828,17 @@ "type": "string", "format": "date-time", "description": "Start of the range, inclusive (RFC 3339).", - "example": "2026-06-01T00:00:00Z" + "examples": [ + "2026-06-01T00:00:00Z" + ] }, "endTime": { "type": "string", "format": "date-time", "description": "End of the range, exclusive (RFC 3339).", - "example": "2026-06-02T00:00:00Z" + "examples": [ + "2026-06-02T00:00:00Z" + ] } } }, @@ -2311,11 +2860,13 @@ ], "default": "day", "description": "Length of each billing time bucket.", - "example": "day" + "examples": [ + "day" + ] }, "BillingAmounts": { "type": "object", - "description": "Total spend across all billable RunPod resources with each cost component broken out, fully prefixed by resource. Backs the aggregate record's amounts and the metadata totals.\n", + "description": "Total spend across all billable Runpod resources with each cost component broken out, fully prefixed by resource. Backs the aggregate record's amounts and the metadata totals.\n", "required": [ "totalAmount", "podGpuAmount", @@ -2337,7 +2888,9 @@ "type": "number", "format": "double", "description": "Total cost in USD for the bucket across all resources.", - "example": 42.34 + "examples": [ + 42.34 + ] }, "podGpuAmount": { "type": "number", @@ -2387,7 +2940,7 @@ "endpointAmount": { "type": "number", "format": "double", - "description": "RunPod public endpoint cost in USD for the bucket." + "description": "Runpod public endpoint cost in USD for the bucket." }, "clusterGpuAmount": { "type": "number", @@ -2407,7 +2960,7 @@ } }, "BillingRecord": { - "description": "A single time-bucketed record of total spend across all billable RunPod resources, with each cost component broken out. Returned by GET /v2/billing.\n", + "description": "A single time-bucketed record of total spend across all billable Runpod resources, with each cost component broken out. Returned by GET /v2/billing.\n", "allOf": [ { "$ref": "#/components/schemas/BillingTimeRange" @@ -2431,7 +2984,9 @@ "type": "number", "format": "double", "description": "Total pod cost in USD for the bucket.", - "example": 12.34 + "examples": [ + 12.34 + ] }, "gpuAmount": { "type": "number", @@ -2468,7 +3023,9 @@ "podId": { "type": "string", "description": "The pod this record bills. When the podId filter is set every record carries that id; otherwise one record is emitted per pod per bucket.\n", - "example": "pod_abc123" + "examples": [ + "pod_abc123" + ] } } } @@ -2489,7 +3046,9 @@ "type": "number", "format": "double", "description": "Total serverless cost in USD for the bucket.", - "example": 8.9 + "examples": [ + 8.9 + ] }, "gpuAmount": { "type": "number", @@ -2531,7 +3090,9 @@ "serverlessId": { "type": "string", "description": "The serverless endpoint this record bills. When the serverlessId filter is set every record carries that id; otherwise one record is emitted per serverless endpoint per bucket.\n", - "example": "ep_abc123" + "examples": [ + "ep_abc123" + ] } } } @@ -2539,7 +3100,7 @@ }, "EndpointBillingAmounts": { "type": "object", - "description": "RunPod public endpoint cost. Backs a record's amounts and the metadata totals.\n", + "description": "Runpod public endpoint cost. Backs a record's amounts and the metadata totals.\n", "required": [ "totalAmount" ], @@ -2548,12 +3109,14 @@ "type": "number", "format": "double", "description": "Total public endpoint cost in USD for the bucket.", - "example": 3.21 + "examples": [ + 3.21 + ] } } }, "EndpointBillingRecord": { - "description": "A single time-bucketed RunPod public endpoint billing record. Returned by GET /v2/billing/endpoints.\n", + "description": "A single time-bucketed Runpod public endpoint billing record. Returned by GET /v2/billing/endpoints.\n", "allOf": [ { "$ref": "#/components/schemas/BillingTimeRange" @@ -2576,7 +3139,9 @@ "type": "number", "format": "double", "description": "Total network volume cost in USD for the bucket, across standard and high-performance storage.\n", - "example": 5.79 + "examples": [ + 5.79 + ] }, "standardAmount": { "type": "number", @@ -2608,7 +3173,9 @@ "networkVolumeId": { "type": "string", "description": "The network volume this record bills. When the networkVolumeId filter is set every record carries that id; otherwise one record is emitted per network volume per bucket.\n", - "example": "vol_abc123" + "examples": [ + "vol_abc123" + ] } } } @@ -2628,7 +3195,9 @@ "type": "number", "format": "double", "description": "Total Instant Cluster cost in USD for the bucket.", - "example": 99 + "examples": [ + 99 + ] }, "gpuAmount": { "type": "number", @@ -2665,7 +3234,9 @@ "clusterId": { "type": "string", "description": "The Instant Cluster this record bills. When the clusterId filter is set every record carries that id; otherwise one record is emitted per cluster per bucket.\n", - "example": "cluster_abc123" + "examples": [ + "cluster_abc123" + ] } } } @@ -2699,8 +3270,10 @@ "type": "object", "properties": { "podId": { - "type": "string", - "nullable": true, + "type": [ + "string", + "null" + ], "description": "The podId filter applied, if any." } } @@ -2716,8 +3289,10 @@ "type": "object", "properties": { "serverlessId": { - "type": "string", - "nullable": true, + "type": [ + "string", + "null" + ], "description": "The serverlessId filter applied, if any." } } @@ -2733,8 +3308,10 @@ "type": "object", "properties": { "networkVolumeId": { - "type": "string", - "nullable": true, + "type": [ + "string", + "null" + ], "description": "The networkVolumeId filter applied, if any." } } @@ -2750,8 +3327,10 @@ "type": "object", "properties": { "clusterId": { - "type": "string", - "nullable": true, + "type": [ + "string", + "null" + ], "description": "The clusterId filter applied, if any." } } @@ -2899,7 +3478,7 @@ }, "ListBillingResponse": { "type": "object", - "description": "Aggregated billing records across all RunPod resources.", + "description": "Aggregated billing records across all Runpod resources.", "required": [ "records", "metadata" @@ -2956,7 +3535,7 @@ }, "ListEndpointBillingResponse": { "type": "object", - "description": "Billing records for RunPod public endpoints.", + "description": "Time-bucketed Runpod public endpoint billing records plus metadata for the resolved query, record count, and total endpoint amount.\n", "required": [ "records", "metadata" @@ -2975,7 +3554,7 @@ }, "ListNetworkVolumeBillingResponse": { "type": "object", - "description": "Billing records for network volumes.", + "description": "Time-bucketed network volume billing records plus metadata for the resolved query, record count, distinct volume count, and storage totals.\n", "required": [ "records", "metadata" @@ -2994,7 +3573,7 @@ }, "ListClusterBillingResponse": { "type": "object", - "description": "Billing records for Instant Clusters.", + "description": "Time-bucketed Instant Cluster billing records plus metadata for the resolved query, record count, distinct cluster count, and compute totals.\n", "required": [ "records", "metadata" @@ -3013,44 +3592,44 @@ }, "ErrorResponse": { "type": "object", + "required": [ + "title", + "status", + "detail" + ], "properties": { "title": { "type": "string", "description": "Short human-readable summary", - "example": "Not Found" + "examples": [ + "Not Found" + ] }, "status": { "type": "integer", "description": "HTTP status code", - "example": 404 + "examples": [ + 404 + ] }, "detail": { "type": "string", "description": "Human-readable explanation", - "example": "pod not found" - } - } - }, - "ValidatationErrorResponse": { - "type": "object", - "properties": { - "title": { - "type": "string", - "description": "Short human-readable summary", - "example": "Unprocessable Entity" - }, - "status": { - "type": "integer", - "description": "HTTP status code", - "example": 422 + "examples": [ + "pod not found" + ] }, "errors": { "type": "array", + "description": "Individual request-validation failures.", "items": { - "type": "string", - "example": "$: minProperties: got 0, want 1" + "type": "string" }, - "description": "Human-readable explanation" + "examples": [ + [ + "$: additional properties 'bogus' not allowed" + ] + ] } } } @@ -3072,10 +3651,69 @@ "application/json": { "schema": { "$ref": "#/components/schemas/ListPodsResponse" + }, + "examples": { + "pods": { + "summary": "Successful response", + "value": { + "pods": [ + { + "id": "7h9k2m4n6p", + "name": "pytorch-training", + "image": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1", + "args": "", + "disk": 50, + "ports": [ + "8888/http", + "22/tcp" + ], + "env": { + "MODEL_NAME": "llama-3" + }, + "registry": null, + "status": "RUNNING", + "actions": [ + "stop", + "restart", + "terminate" + ], + "mounts": { + "persistent": { + "size": 20, + "path": "/workspace" + } + }, + "gpu": { + "id": "NVIDIA GeForce RTX 4090", + "count": 1 + }, + "cloud": "SECURE", + "dataCenterId": "US-KS-2", + "template": "9x4m2p7v", + "cost": 0.44, + "locked": false, + "globalNetworking": { + "enabled": false + }, + "runtime": { + "uptime": 3600 + }, + "createdAt": "2026-06-01T12:00:00Z", + "startedAt": "2026-06-01T12:02:00Z" + } + ] + } + } } } } }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, "default": { "description": "Error", "content": { @@ -3091,7 +3729,7 @@ "post": { "operationId": "createPod", "summary": "Create a pod", - "description": "Creates a new pod. Specify `gpu` for compute.\nContainerConfig fields can be spread from a template response.\n", + "description": "Creates a new pod. `name` and `image` are always required; supply\nexactly one of `gpu` or `cpu` to select compute (a GPU or a CPU pod).\nRemaining container settings can be spread from a template response —\nsee `CreatePodRequest` for the full body.\n\nReturns `201` with the created pod. Provisioning is asynchronous: the\npod starts in `PROVISIONING`, transitions through `STARTING`, and\nreaches `RUNNING` once its container is healthy. Poll `getPod` (or\nwatch the pod's `status`) to observe readiness rather than assuming\nthe pod is running when this call returns.\n", "tags": [ "Pods" ], @@ -3101,6 +3739,20 @@ "application/json": { "schema": { "$ref": "#/components/schemas/CreatePodRequest" + }, + "examples": { + "gpuPod": { + "summary": "GPU pod", + "value": { + "name": "pytorch-training", + "image": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1", + "gpu": { + "id": "NVIDIA GeForce RTX 4090", + "count": 1 + }, + "disk": 50 + } + } } } } @@ -3112,10 +3764,68 @@ "application/json": { "schema": { "$ref": "#/components/schemas/Pod" + }, + "examples": { + "pod": { + "summary": "Successful response", + "value": { + "id": "7h9k2m4n6p", + "name": "pytorch-training", + "image": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1", + "args": "", + "disk": 50, + "ports": [ + "8888/http", + "22/tcp" + ], + "env": { + "MODEL_NAME": "llama-3" + }, + "registry": null, + "status": "PROVISIONING", + "actions": [ + "start", + "terminate" + ], + "mounts": { + "persistent": { + "size": 20, + "path": "/workspace" + } + }, + "gpu": { + "id": "NVIDIA GeForce RTX 4090", + "count": 1 + }, + "cloud": "SECURE", + "dataCenterId": "US-KS-2", + "template": "9x4m2p7v", + "cost": 0.44, + "locked": false, + "globalNetworking": { + "enabled": false + }, + "runtime": {}, + "createdAt": "2026-06-01T12:00:00Z", + "startedAt": null + } + } } } } }, + "400": { + "$ref": "#/components/responses/BadRequestError" + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, + "422": { + "$ref": "#/components/responses/UnprocessableEntityError" + }, "default": { "description": "Error", "content": { @@ -3156,19 +3866,67 @@ "application/json": { "schema": { "$ref": "#/components/schemas/Pod" + }, + "examples": { + "pod": { + "summary": "Successful response", + "value": { + "id": "7h9k2m4n6p", + "name": "pytorch-training", + "image": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1", + "args": "", + "disk": 50, + "ports": [ + "8888/http", + "22/tcp" + ], + "env": { + "MODEL_NAME": "llama-3" + }, + "registry": null, + "status": "RUNNING", + "actions": [ + "stop", + "restart", + "terminate" + ], + "mounts": { + "persistent": { + "size": 20, + "path": "/workspace" + } + }, + "gpu": { + "id": "NVIDIA GeForce RTX 4090", + "count": 1 + }, + "cloud": "SECURE", + "dataCenterId": "US-KS-2", + "template": "9x4m2p7v", + "cost": 0.44, + "locked": false, + "globalNetworking": { + "enabled": false + }, + "runtime": { + "uptime": 3600 + }, + "createdAt": "2026-06-01T12:00:00Z", + "startedAt": "2026-06-01T12:02:00Z" + } + } } } } }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, "404": { - "description": "Pod not found", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } + "$ref": "#/components/responses/NotFoundError" }, "default": { "description": "Error", @@ -3185,7 +3943,7 @@ "patch": { "operationId": "updatePod", "summary": "Update a pod", - "description": "Updates pod configuration. Only provided fields are changed.", + "description": "Partially updates a pod's configuration. This is a PATCH: only the\nfields present in the body are changed, and omitted fields are left\nuntouched. Use empty values only when you explicitly mean to clear a\nfield (for example, set `registry` to `null` or set `ports` to `[]`).\nSee `UpdatePodRequest` for the full body.\n\nMutable fields: `name`, `image`, `args`, `disk`, `ports`, `env`,\n`registry`, `mounts`, `locked`, and `globalNetworking`. Some changes\napply immediately while others (e.g. `globalNetworking`) take effect\non the pod's next start/restart, as noted on the individual fields.\n\nReturns `200` with the full updated pod.\n", "tags": [ "Pods" ], @@ -3195,6 +3953,14 @@ "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePodRequest" + }, + "examples": { + "renamePod": { + "summary": "Rename pod", + "value": { + "name": "renamed-training-pod" + } + } } } } @@ -3206,19 +3972,73 @@ "application/json": { "schema": { "$ref": "#/components/schemas/Pod" + }, + "examples": { + "pod": { + "summary": "Successful response", + "value": { + "id": "7h9k2m4n6p", + "name": "renamed-training-pod", + "image": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1", + "args": "", + "disk": 50, + "ports": [ + "8888/http", + "22/tcp" + ], + "env": { + "MODEL_NAME": "llama-3" + }, + "registry": null, + "status": "RUNNING", + "actions": [ + "stop", + "restart", + "terminate" + ], + "mounts": { + "persistent": { + "size": 20, + "path": "/workspace" + } + }, + "gpu": { + "id": "NVIDIA GeForce RTX 4090", + "count": 1 + }, + "cloud": "SECURE", + "dataCenterId": "US-KS-2", + "template": "9x4m2p7v", + "cost": 0.44, + "locked": false, + "globalNetworking": { + "enabled": false + }, + "runtime": { + "uptime": 3600 + }, + "createdAt": "2026-06-01T12:00:00Z", + "startedAt": "2026-06-01T12:02:00Z" + } + } } } } }, + "400": { + "$ref": "#/components/responses/BadRequestError" + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, "404": { - "description": "Pod not found", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } + "$ref": "#/components/responses/NotFoundError" + }, + "422": { + "$ref": "#/components/responses/UnprocessableEntityError" }, "default": { "description": "Error", @@ -3235,23 +4055,22 @@ "delete": { "operationId": "deletePod", "summary": "Terminate a pod", - "description": "Permanently terminates and deletes a pod.", + "description": "Permanently terminates and deletes a pod. This is irreversible:\ncompute is released, any `mounts.persistent` host-local storage is\ndestroyed with it (a `mounts.network` volume is only detached — the\nvolume itself is not deleted), and the pod no longer appears in\n`listPods`.\n", "tags": [ "Pods" ], "responses": { "204": { - "description": "Terminated" + "description": "Deleted. Response has no body." + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" }, "404": { - "description": "Pod not found", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } + "$ref": "#/components/responses/NotFoundError" }, "default": { "description": "Error", @@ -3326,39 +4145,26 @@ "content": { "text/event-stream": { "schema": { - "type": "object", - "properties": { - "source": { - "type": "string", - "enum": [ - "container", - "system" - ], - "example": "container" - }, - "line": { - "type": "string", - "example": "Model loaded." - }, - "ts": { - "type": "string", - "format": "date-time", - "example": "2026-05-01T22:00:00Z" - } + "type": "string", + "description": "Server-Sent Events stream. Each event includes an `id:` line and a JSON `data:` payload with `source`, `line`, and `ts` fields." + }, + "examples": { + "logLine": { + "summary": "Successful response", + "value": "id: 2026-06-01T12:02:03Z/000000000001\ndata: {\"ts\":\"2026-06-01T12:02:03Z\",\"source\":\"container\",\"line\":\"Model loaded.\"}\n" } } } } }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, "404": { - "description": "Pod not found", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } + "$ref": "#/components/responses/NotFoundError" }, "default": { "description": "Error", @@ -3388,7 +4194,7 @@ "post": { "operationId": "podAction", "summary": "Trigger a pod state transition", - "description": "Triggers a state transition on a pod. Valid actions depend on the current status\nand are listed in the pod's `actions` field.\n", + "description": "Triggers a state transition on a pod. Send a JSON body with a single\n`action` field, e.g. `{ \"action\": \"stop\" }`.\n\nValid actions:\n- `start` — boot a stopped pod (`EXITED` or `ERROR`) back toward\n `RUNNING`.\n- `stop` — stop a running or provisioning pod, releasing GPU/CPU\n compute while keeping its disk. The pod moves to `EXITED`.\n- `restart` — restart a `RUNNING` pod's container in place.\n- `terminate` — permanently delete the pod and release its resources\n (equivalent to `deletePod`).\n\nWhich actions are valid depends on the pod's current status, and the\ncurrently permitted set is published in the pod's `actions` field:\n`RUNNING` allows `stop`/`restart`/`terminate`; `EXITED` and `ERROR`\nallow `start`/`terminate`; `PROVISIONING` and `STARTING` allow\n`stop`/`terminate`.\n\n`start`, `stop`, and `restart` return `200` with the updated pod.\n`terminate` returns `204` with no body. Requesting an action that is\nnot valid for the pod's current status returns `409`.\n", "tags": [ "Pods" ], @@ -3398,6 +4204,14 @@ "application/json": { "schema": { "$ref": "#/components/schemas/PodActionRequest" + }, + "examples": { + "startPod": { + "summary": "Start pod", + "value": { + "action": "start" + } + } } } } @@ -3409,22 +4223,73 @@ "application/json": { "schema": { "$ref": "#/components/schemas/Pod" + }, + "examples": { + "pod": { + "summary": "Successful response", + "value": { + "id": "7h9k2m4n6p", + "name": "pytorch-training", + "image": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1", + "args": "", + "disk": 50, + "ports": [ + "8888/http", + "22/tcp" + ], + "env": { + "MODEL_NAME": "llama-3" + }, + "registry": null, + "status": "RUNNING", + "actions": [ + "stop", + "restart", + "terminate" + ], + "mounts": { + "persistent": { + "size": 20, + "path": "/workspace" + } + }, + "gpu": { + "id": "NVIDIA GeForce RTX 4090", + "count": 1 + }, + "cloud": "SECURE", + "dataCenterId": "US-KS-2", + "template": "9x4m2p7v", + "cost": 0.44, + "locked": false, + "globalNetworking": { + "enabled": false + }, + "runtime": { + "uptime": 3600 + }, + "createdAt": "2026-06-01T12:00:00Z", + "startedAt": "2026-06-01T12:02:00Z" + } + } } } } }, "204": { - "description": "Pod terminated (for action=terminate)" + "description": "Only returned when `action=terminate`; response has no body." + }, + "400": { + "$ref": "#/components/responses/BadRequestError" + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" }, "404": { - "description": "Pod not found", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } + "$ref": "#/components/responses/NotFoundError" }, "409": { "description": "Action not valid for current pod status", @@ -3436,6 +4301,9 @@ } } }, + "422": { + "$ref": "#/components/responses/UnprocessableEntityError" + }, "default": { "description": "Error", "content": { @@ -3464,10 +4332,68 @@ "application/json": { "schema": { "$ref": "#/components/schemas/ListEndpointsResponse" + }, + "examples": { + "endpoints": { + "summary": "Successful response", + "value": { + "endpoints": [ + { + "id": "4m7x2k9q", + "name": "image-generator", + "type": "QUEUE_BASED", + "requestUrls": { + "run": "https://api.runpod.ai/v2/4m7x2k9q/run", + "runSync": "https://api.runpod.ai/v2/4m7x2k9q/runsync" + }, + "image": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1", + "args": "", + "disk": 20, + "ports": [ + "8000/http" + ], + "env": { + "MODEL_NAME": "sdxl" + }, + "registry": null, + "gpu": { + "pools": [ + "ADA_24" + ], + "count": 1 + }, + "workers": { + "min": 0, + "max": 5 + }, + "scaling": { + "type": "QUEUE_DELAY", + "value": 4, + "idleTimeout": 5 + }, + "dataCenterIds": [ + "US-KS-2" + ], + "networkVolumes": [ + "2q9m7x4c" + ], + "timeout": 300000, + "flashboot": "OFF", + "createdAt": "2026-06-01T12:00:00Z" + } + ] + } + } } } } }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, "default": { "description": "Error", "content": { @@ -3483,7 +4409,7 @@ "post": { "operationId": "createEndpoint", "summary": "Create a serverless endpoint", - "description": "Creates a serverless endpoint. Specify `gpu` for compute (CPU serverless\nendpoints are read-only). ContainerConfig fields can be spread from a\ntemplate response.\n", + "description": "Creates a serverless endpoint. Specify `gpu` for compute (CPU\nserverless endpoints are read-only). Container settings can be spread\nfrom a template response — see `CreateEndpointRequest` for the full\nbody.\n\nReturns `201` with the created endpoint. The endpoint can accept jobs\nimmediately, but starts with no active workers unless `workers.min`\nis greater than 0. Workers are provisioned on demand and autoscaled\nbetween `workers.min` and `workers.max` according to the `scaling`\npolicy, so the first request to an idle endpoint may incur cold-start\nlatency while a worker pulls its image and boots.\n", "tags": [ "Serverless" ], @@ -3493,6 +4419,34 @@ "application/json": { "schema": { "$ref": "#/components/schemas/CreateEndpointRequest" + }, + "examples": { + "serverlessEndpoint": { + "summary": "Serverless endpoint", + "value": { + "name": "image-generator", + "image": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1", + "gpu": { + "pools": [ + "ADA_24" + ], + "count": 1 + }, + "workers": { + "min": 0, + "max": 5 + }, + "scaling": { + "type": "QUEUE_DELAY", + "value": 4, + "idleTimeout": 5 + }, + "dataCenterIds": [ + "US-KS-2" + ], + "timeout": 300000 + } + } } } } @@ -3504,10 +4458,70 @@ "application/json": { "schema": { "$ref": "#/components/schemas/Endpoint" + }, + "examples": { + "endpoint": { + "summary": "Successful response", + "value": { + "id": "4m7x2k9q", + "name": "image-generator", + "type": "QUEUE_BASED", + "requestUrls": { + "run": "https://api.runpod.ai/v2/4m7x2k9q/run", + "runSync": "https://api.runpod.ai/v2/4m7x2k9q/runsync" + }, + "image": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1", + "args": "", + "disk": 20, + "ports": [ + "8000/http" + ], + "env": { + "MODEL_NAME": "sdxl" + }, + "registry": null, + "gpu": { + "pools": [ + "ADA_24" + ], + "count": 1 + }, + "workers": { + "min": 0, + "max": 5 + }, + "scaling": { + "type": "QUEUE_DELAY", + "value": 4, + "idleTimeout": 5 + }, + "dataCenterIds": [ + "US-KS-2" + ], + "networkVolumes": [ + "2q9m7x4c" + ], + "timeout": 300000, + "flashboot": "OFF", + "createdAt": "2026-06-01T12:00:00Z" + } + } } } } }, + "400": { + "$ref": "#/components/responses/BadRequestError" + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, + "422": { + "$ref": "#/components/responses/UnprocessableEntityError" + }, "default": { "description": "Error", "content": { @@ -3548,19 +4562,65 @@ "application/json": { "schema": { "$ref": "#/components/schemas/Endpoint" + }, + "examples": { + "endpoint": { + "summary": "Successful response", + "value": { + "id": "4m7x2k9q", + "name": "image-generator", + "type": "LOAD_BALANCING", + "requestUrls": { + "base": "https://4m7x2k9q.api.runpod.ai" + }, + "image": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1", + "args": "", + "disk": 20, + "ports": [ + "8000/http" + ], + "env": { + "MODEL_NAME": "sdxl" + }, + "registry": null, + "gpu": { + "pools": [ + "ADA_24" + ], + "count": 1 + }, + "workers": { + "min": 0, + "max": 5 + }, + "scaling": { + "type": "QUEUE_DELAY", + "value": 4, + "idleTimeout": 5 + }, + "dataCenterIds": [ + "US-KS-2" + ], + "networkVolumes": [ + "2q9m7x4c" + ], + "timeout": 300000, + "flashboot": "OFF", + "createdAt": "2026-06-01T12:00:00Z" + } + } } } } }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, "404": { - "description": "Serverless endpoint not found", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } + "$ref": "#/components/responses/NotFoundError" }, "default": { "description": "Error", @@ -3577,7 +4637,7 @@ "patch": { "operationId": "updateEndpoint", "summary": "Update a serverless endpoint", - "description": "Updates serverless endpoint configuration. Only provided fields are changed.", + "description": "Partially updates a serverless endpoint. This is a PATCH: only the\nfields present in the body are changed; omitted fields are left\nuntouched. See `UpdateEndpointRequest` for the full body.\n\nMutable fields: `name`, `gpu`, `workers` (`min`/`max`), `scaling`\n(`type`/`value`/`idleTimeout`), `dataCenterIds`, `networkVolumes`,\n`timeout`, `flashboot`, and the container settings (`image`, `args`,\n`disk`, `ports`, `env`, `registry`).\n\nReturns `200` with the full updated endpoint. Effect timing differs\nby field: scaling and worker-bound settings (`workers`, `scaling`,\n`timeout`) are applied to the autoscaler promptly, while\ncontainer-affecting changes (e.g. `image`, `env`) create a new\nendpoint release that rolls out as workers cycle — in-flight workers\nkeep the previous version until they are replaced. Track rollout via\n`listEndpointReleases`.\n", "tags": [ "Serverless" ], @@ -3587,6 +4647,22 @@ "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEndpointRequest" + }, + "examples": { + "scaleEndpoint": { + "summary": "Scale endpoint", + "value": { + "workers": { + "min": 1, + "max": 10 + }, + "scaling": { + "type": "REQUEST_COUNT", + "value": 8, + "idleTimeout": 10 + } + } + } } } } @@ -3598,19 +4674,72 @@ "application/json": { "schema": { "$ref": "#/components/schemas/Endpoint" + }, + "examples": { + "endpoint": { + "summary": "Successful response", + "value": { + "id": "4m7x2k9q", + "name": "image-generator", + "type": "QUEUE_BASED", + "requestUrls": { + "run": "https://api.runpod.ai/v2/4m7x2k9q/run", + "runSync": "https://api.runpod.ai/v2/4m7x2k9q/runsync" + }, + "image": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1", + "args": "", + "disk": 20, + "ports": [ + "8000/http" + ], + "env": { + "MODEL_NAME": "sdxl" + }, + "registry": null, + "gpu": { + "pools": [ + "ADA_24" + ], + "count": 1 + }, + "workers": { + "min": 1, + "max": 10 + }, + "scaling": { + "type": "REQUEST_COUNT", + "value": 8, + "idleTimeout": 10 + }, + "dataCenterIds": [ + "US-KS-2" + ], + "networkVolumes": [ + "2q9m7x4c" + ], + "timeout": 300000, + "flashboot": "OFF", + "createdAt": "2026-06-01T12:00:00Z" + } + } } } } }, + "400": { + "$ref": "#/components/responses/BadRequestError" + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, "404": { - "description": "Serverless endpoint not found", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } + "$ref": "#/components/responses/NotFoundError" + }, + "422": { + "$ref": "#/components/responses/UnprocessableEntityError" }, "default": { "description": "Error", @@ -3627,23 +4756,22 @@ "delete": { "operationId": "deleteEndpoint", "summary": "Delete a serverless endpoint", - "description": "Permanently deletes a serverless endpoint and its bound template.", + "description": "Permanently deletes a serverless endpoint and its bound template.\nThis is irreversible: all workers are terminated and any queued or\nin-progress jobs are cancelled.\n", "tags": [ "Serverless" ], "responses": { "204": { - "description": "Deleted" + "description": "Deleted. Response has no body." + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" }, "404": { - "description": "Serverless endpoint not found", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } + "$ref": "#/components/responses/NotFoundError" }, "default": { "description": "Error", @@ -3674,7 +4802,7 @@ "get": { "operationId": "listEndpointWorkers", "summary": "List serverless endpoint workers", - "description": "Returns the active workers for a serverless endpoint plus a summary of\nworker counts. Each worker's `status` is derived by reconciling the\nworker pod's lifecycle status with the endpoint's live job-queue view.\nWhen the job-queue view is unavailable the response degrades to the\npod-derived status and counts.\n", + "description": "Lists the active workers for a serverless endpoint.\n\n**Returns.** A `200` with a `ListEndpointWorkersResponse`: a\n`workers` array (one entry per active worker, each carrying its `id`,\n`status`, and runtime details) plus a `summary` of worker counts\ngrouped by status. Only currently active workers are included;\nscaled-down workers are not returned.\n\n**How `status` is determined.** Each worker's `status` is derived by\nreconciling the worker pod's lifecycle status with the endpoint's\nlive job-queue view (which workers are actively serving requests).\nWhen the job-queue view is unavailable, the response degrades\ngracefully: the shape is unchanged, but each `status` and the summary\ncounts fall back to pod lifecycle alone.\n", "tags": [ "Serverless" ], @@ -3685,19 +4813,48 @@ "application/json": { "schema": { "$ref": "#/components/schemas/ListEndpointWorkersResponse" + }, + "examples": { + "workers": { + "summary": "Successful response", + "value": { + "endpointVersion": 4, + "summary": { + "running": 1, + "idle": 1, + "initializing": 0, + "throttled": 0, + "unhealthy": 0, + "total": 2 + }, + "workers": [ + { + "id": "8g3n5t6r", + "status": "RUNNING", + "isStale": false, + "version": 4, + "gpuCount": 1, + "image": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1", + "uptimeSeconds": 3600, + "gpuTypeId": "NVIDIA GeForce RTX 4090", + "dataCenterId": "US-KS-2", + "startedAt": "2026-06-01T12:05:00Z" + } + ] + } + } } } } }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, "404": { - "description": "Serverless endpoint not found", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } + "$ref": "#/components/responses/NotFoundError" }, "default": { "description": "Error", @@ -3739,19 +4896,50 @@ "application/json": { "schema": { "$ref": "#/components/schemas/ListEndpointReleasesResponse" + }, + "examples": { + "releases": { + "summary": "Successful response", + "value": { + "endpointVersion": 4, + "rollout": { + "inProgress": true, + "workersOnLatest": 1, + "workersTotal": 2, + "percentOnLatest": 50 + }, + "releases": [ + { + "id": "5r9x2m7q", + "version": 4, + "source": "MANUAL", + "buildId": null, + "createdByUserId": null, + "workerCount": 2, + "createdAt": "2026-06-01T12:10:00Z", + "diff": [ + { + "field": "workers.max", + "old": 5, + "new": 10 + } + ] + } + ] + } + } } } } }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, "404": { - "description": "Serverless endpoint not found", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } + "$ref": "#/components/responses/NotFoundError" }, "default": { "description": "Error", @@ -3836,39 +5024,26 @@ "content": { "text/event-stream": { "schema": { - "type": "object", - "properties": { - "source": { - "type": "string", - "enum": [ - "container", - "system" - ], - "example": "container" - }, - "line": { - "type": "string", - "example": "Model loaded." - }, - "ts": { - "type": "string", - "format": "date-time", - "example": "2026-05-01T22:00:00Z" - } + "type": "string", + "description": "Server-Sent Events stream. Each event includes an `id:` line and a JSON `data:` payload with `source`, `line`, and `ts` fields." + }, + "examples": { + "logLine": { + "summary": "Successful response", + "value": "id: 2026-06-01T12:05:04Z/000000000042\ndata: {\"ts\":\"2026-06-01T12:05:04Z\",\"source\":\"container\",\"line\":\"Worker ready.\"}\n" } } } } }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, "404": { - "description": "Worker not found", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } + "$ref": "#/components/responses/NotFoundError" }, "default": { "description": "Error", @@ -3898,10 +5073,48 @@ "application/json": { "schema": { "$ref": "#/components/schemas/ListTemplatesResponse" + }, + "examples": { + "templates": { + "summary": "Successful response", + "value": { + "templates": [ + { + "id": "9x4m2p7v", + "name": "PyTorch GPU Template", + "image": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1", + "args": "", + "disk": 50, + "mounts": { + "persistent": { + "size": 20, + "path": "/workspace" + } + }, + "ports": [ + "8888/http" + ], + "env": { + "JUPYTER_ENABLE_LAB": "yes" + }, + "registry": null, + "serverless": false, + "public": false, + "category": "NVIDIA" + } + ] + } + } } } } }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, "default": { "description": "Error", "content": { @@ -3917,6 +5130,7 @@ "post": { "operationId": "createTemplate", "summary": "Create a template", + "description": "Creates a reusable container-configuration preset — image, disk,\nports, env, registry, and mount settings — for pods and serverless\nendpoints. `createPod` and `createEndpoint` don't take a template ID;\ninstead, spread a template's fields into the request body directly.\nReturns the created template.\n", "tags": [ "Templates" ], @@ -3926,6 +5140,31 @@ "application/json": { "schema": { "$ref": "#/components/schemas/CreateTemplateRequest" + }, + "examples": { + "podTemplate": { + "summary": "Pod template", + "value": { + "name": "PyTorch GPU Template", + "image": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1", + "category": "NVIDIA", + "disk": 50, + "ports": [ + "8888/http" + ], + "env": { + "JUPYTER_ENABLE_LAB": "yes" + }, + "mounts": { + "persistent": { + "size": 20, + "path": "/workspace" + } + }, + "serverless": false, + "public": false + } + } } } } @@ -3937,12 +5176,52 @@ "application/json": { "schema": { "$ref": "#/components/schemas/Template" + }, + "examples": { + "template": { + "summary": "Successful response", + "value": { + "id": "9x4m2p7v", + "name": "PyTorch GPU Template", + "image": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1", + "args": "", + "disk": 50, + "mounts": { + "persistent": { + "size": 20, + "path": "/workspace" + } + }, + "ports": [ + "8888/http" + ], + "env": { + "JUPYTER_ENABLE_LAB": "yes" + }, + "registry": null, + "serverless": false, + "public": false, + "category": "NVIDIA" + } + } } } } }, - "default": { - "description": "Error", + "400": { + "$ref": "#/components/responses/BadRequestError" + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, + "422": { + "$ref": "#/components/responses/UnprocessableEntityError" + }, + "default": { + "description": "Error", "content": { "application/problem+json": { "schema": { @@ -3969,6 +5248,7 @@ "get": { "operationId": "getTemplate", "summary": "Get a template", + "description": "Returns the full configuration of a single template by ID.", "tags": [ "Templates" ], @@ -3979,19 +5259,46 @@ "application/json": { "schema": { "$ref": "#/components/schemas/Template" + }, + "examples": { + "template": { + "summary": "Successful response", + "value": { + "id": "9x4m2p7v", + "name": "PyTorch GPU Template", + "image": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1", + "args": "", + "disk": 50, + "mounts": { + "persistent": { + "size": 20, + "path": "/workspace" + } + }, + "ports": [ + "8888/http" + ], + "env": { + "JUPYTER_ENABLE_LAB": "yes" + }, + "registry": null, + "serverless": false, + "public": false, + "category": "NVIDIA" + } + } } } } }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, "404": { - "description": "Template not found", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } + "$ref": "#/components/responses/NotFoundError" }, "default": { "description": "Error", @@ -4008,7 +5315,7 @@ "patch": { "operationId": "updateTemplate", "summary": "Update a template", - "description": "Updates template configuration. Only provided fields are changed.", + "description": "Partially updates a template. This is a PATCH: only the fields\npresent in the body are changed; omitted fields are left untouched.\nSee `UpdateTemplateRequest` for the full body.\n\nMutable fields: `name`, `image`, `args`, `disk`, `ports`, `env`,\n`registry`, `mounts`, `serverless`, `public`, and `category`.\n\nOnly the template's owner can update it (authenticated via the\nrequest's API key); other users' templates are neither visible nor\nmutable. Returns `200` with the full updated template. Pods and\nendpoints already created from this template are not changed\nretroactively — the template is a snapshot applied at creation time.\n", "tags": [ "Templates" ], @@ -4018,6 +5325,14 @@ "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTemplateRequest" + }, + "examples": { + "renameTemplate": { + "summary": "Rename template", + "value": { + "name": "Renamed PyTorch Template" + } + } } } } @@ -4029,19 +5344,52 @@ "application/json": { "schema": { "$ref": "#/components/schemas/Template" + }, + "examples": { + "template": { + "summary": "Successful response", + "value": { + "id": "9x4m2p7v", + "name": "Renamed PyTorch Template", + "image": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1", + "args": "", + "disk": 50, + "mounts": { + "persistent": { + "size": 20, + "path": "/workspace" + } + }, + "ports": [ + "8888/http" + ], + "env": { + "JUPYTER_ENABLE_LAB": "yes" + }, + "registry": null, + "serverless": false, + "public": false, + "category": "NVIDIA" + } + } } } } }, + "400": { + "$ref": "#/components/responses/BadRequestError" + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, "404": { - "description": "Template not found", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } + "$ref": "#/components/responses/NotFoundError" + }, + "422": { + "$ref": "#/components/responses/UnprocessableEntityError" }, "default": { "description": "Error", @@ -4058,15 +5406,16 @@ "delete": { "operationId": "deleteTemplate", "summary": "Delete a template", + "description": "Permanently deletes a template by ID. Rejected if the template is\ncurrently referenced by a pod (see that pod's `template` field) or\nbound to a serverless endpoint.\n", "tags": [ "Templates" ], "responses": { "204": { - "description": "Deleted" + "description": "Deleted. Response has no body." }, - "404": { - "description": "Template not found", + "400": { + "description": "Template is in use by a pod or serverless endpoint and cannot be deleted", "content": { "application/problem+json": { "schema": { @@ -4075,6 +5424,15 @@ } } }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, + "404": { + "$ref": "#/components/responses/NotFoundError" + }, "default": { "description": "Error", "content": { @@ -4088,24 +5446,13 @@ } } }, - "/v2/tags": { + "/v2/network-volumes": { "get": { - "operationId": "listTags", - "summary": "List tags", - "description": "Returns all tags owned by the authenticated user.", + "operationId": "listNetworkVolumes", + "summary": "List network volumes", + "description": "Returns all network volumes owned by the authenticated user.", "tags": [ - "Tags" - ], - "parameters": [ - { - "name": "include", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "Comma-separated optional expansions. Supported value: `resources`." - } + "Network Volumes" ], "responses": { "200": { @@ -4113,11 +5460,33 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ListTagsResponse" + "$ref": "#/components/schemas/ListNetworkVolumesResponse" + }, + "examples": { + "networkVolumes": { + "summary": "Successful response", + "value": { + "networkVolumes": [ + { + "id": "2q9m7x4c", + "name": "training-dataset", + "size": 100, + "dataCenter": "US-KS-2", + "type": "HIGH_PERFORMANCE" + } + ] + } + } } } } }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, "default": { "description": "Error", "content": { @@ -4131,18 +5500,29 @@ } }, "post": { - "operationId": "createTag", - "summary": "Create a tag", - "description": "Creates a user-defined key-value tag.", + "operationId": "createNetworkVolume", + "summary": "Create a network volume", + "description": "Provisions a new network volume — persistent, network-attached\nstorage that can be mounted into pods and serverless workers.\nRequired inputs are `name`, `size` (in GB), and `dataCenter`; an\noptional `type` selects the storage tier and is immutable after\ncreation. See `CreateNetworkVolumeRequest` for the size bounds and\ntier options.\n\nThis creates a billable persistent resource that keeps incurring\nstorage charges until it is deleted. Returns `201` with the created\nnetwork volume, including its assigned `id`.\n", "tags": [ - "Tags" + "Network Volumes" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CreateTagRequest" + "$ref": "#/components/schemas/CreateNetworkVolumeRequest" + }, + "examples": { + "networkVolume": { + "summary": "Network volume", + "value": { + "name": "training-dataset", + "dataCenter": "US-KS-2", + "size": 50, + "type": "HIGH_PERFORMANCE" + } + } } } } @@ -4153,20 +5533,34 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Tag" + "$ref": "#/components/schemas/NetworkVolume" + }, + "examples": { + "networkVolume": { + "summary": "Successful response", + "value": { + "id": "2q9m7x4c", + "name": "training-dataset", + "size": 50, + "dataCenter": "US-KS-2", + "type": "HIGH_PERFORMANCE" + } + } } } } }, "400": { - "description": "Invalid request body", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } + "$ref": "#/components/responses/BadRequestError" + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, + "422": { + "$ref": "#/components/responses/UnprocessableEntityError" }, "default": { "description": "Error", @@ -4181,7 +5575,7 @@ } } }, - "/v2/tags/{id}": { + "/v2/network-volumes/{id}": { "parameters": [ { "name": "id", @@ -4190,27 +5584,16 @@ "schema": { "type": "string" }, - "description": "Tag identifier", - "example": "tag_abc123" + "description": "Network volume identifier", + "example": "agv6w2qcg7" } ], "get": { - "operationId": "getTag", - "summary": "Get a tag", - "description": "Returns a single tag by ID.", + "operationId": "getNetworkVolume", + "summary": "Get a network volume", + "description": "Returns a single network volume by ID.", "tags": [ - "Tags" - ], - "parameters": [ - { - "name": "include", - "in": "query", - "required": false, - "schema": { - "type": "string" - }, - "description": "Comma-separated optional expansions. Supported value: `resources`." - } + "Network Volumes" ], "responses": { "200": { @@ -4218,20 +5601,31 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Tag" + "$ref": "#/components/schemas/NetworkVolume" + }, + "examples": { + "networkVolume": { + "summary": "Successful response", + "value": { + "id": "2q9m7x4c", + "name": "training-dataset", + "size": 100, + "dataCenter": "US-KS-2", + "type": "HIGH_PERFORMANCE" + } + } } } } }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, "404": { - "description": "Tag not found", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } + "$ref": "#/components/responses/NotFoundError" }, "default": { "description": "Error", @@ -4246,18 +5640,26 @@ } }, "patch": { - "operationId": "updateTag", - "summary": "Update a tag", - "description": "Updates a tag. At least one of `key`, `value`, or `resources` must be provided.\n\nWhen `resources` is provided, it replaces the tag's complete resource association set. Resource replacement is not atomic: the API creates missing associations first, then deletes stale associations using separate upstream operations. If an upstream operation fails after earlier operations have succeeded, the response is an error and the tag may contain a partially-applied resource set. Retrying the same request with the same `resources` array is safe and will attempt to converge the tag to the requested set. Use the explicit tag-resource attach/detach operations when you need smaller idempotent association changes.\n", + "operationId": "updateNetworkVolume", + "summary": "Update a network volume", + "description": "Updates mutable fields on a network volume. Only provided fields are changed.\nNote: `size` may only increase; attempts to reduce size will be rejected.\n", "tags": [ - "Tags" + "Network Volumes" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/UpdateTagRequest" + "$ref": "#/components/schemas/UpdateNetworkVolumeRequest" + }, + "examples": { + "resizeNetworkVolume": { + "summary": "Resize network volume", + "value": { + "size": 200 + } + } } } } @@ -4268,33 +5670,25 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Tag" - } - } - } - }, - "404": { - "description": "Tag not found", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "422": { - "description": "Unprocessable request body (missing one of `key`, `value`, or `resources`)", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" + "$ref": "#/components/schemas/NetworkVolume" + }, + "examples": { + "networkVolume": { + "summary": "Successful response", + "value": { + "id": "2q9m7x4c", + "name": "training-dataset", + "size": 200, + "dataCenter": "US-KS-2", + "type": "HIGH_PERFORMANCE" + } + } } } } }, - "default": { - "description": "Error", + "400": { + "description": "Invalid request body or size decrease attempted", "content": { "application/problem+json": { "schema": { @@ -4302,85 +5696,18 @@ } } } - } - } - }, - "delete": { - "operationId": "deleteTag", - "summary": "Delete a tag", - "description": "Deletes a tag. This operation is idempotent; deleting a tag that does not exist returns `204`.", - "tags": [ - "Tags" - ], - "responses": { - "204": { - "description": "Deleted or already absent" }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - } - }, - "/v2/tags/{id}/resources/{resourceType}/{resourceId}": { - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" + "401": { + "$ref": "#/components/responses/UnauthorizedError" }, - "description": "Tag identifier", - "example": "tag_abc123" - }, - { - "name": "resourceType", - "in": "path", - "required": true, - "schema": { - "$ref": "#/components/schemas/TagResourceType" - }, - "description": "Resource type to attach or detach." - }, - { - "name": "resourceId", - "in": "path", - "required": true, - "schema": { - "type": "string" - }, - "description": "Resource identifier to attach or detach.", - "example": "pod_abc123" - } - ], - "put": { - "operationId": "attachTagResource", - "summary": "Attach a resource to a tag", - "description": "Ensures the resource is attached to the tag. This operation is idempotent; attaching an already-associated resource returns `204`.", - "tags": [ - "Tags" - ], - "responses": { - "204": { - "description": "Attached or already associated" + "403": { + "$ref": "#/components/responses/ForbiddenError" }, "404": { - "description": "Tag not found", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } + "$ref": "#/components/responses/NotFoundError" + }, + "422": { + "$ref": "#/components/responses/UnprocessableEntityError" }, "default": { "description": "Error", @@ -4395,25 +5722,24 @@ } }, "delete": { - "operationId": "detachTagResource", - "summary": "Detach a resource from a tag", - "description": "Ensures the resource is detached from the tag. This operation is idempotent; detaching a resource that is not associated with the tag returns `204`.", + "operationId": "deleteNetworkVolume", + "summary": "Delete a network volume", + "description": "Permanently deletes a network volume and releases its storage.", "tags": [ - "Tags" + "Network Volumes" ], "responses": { "204": { - "description": "Detached or already absent" + "description": "Deleted. Response has no body." + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" }, "404": { - "description": "Tag not found", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } + "$ref": "#/components/responses/NotFoundError" }, "default": { "description": "Error", @@ -4428,13 +5754,13 @@ } } }, - "/v2/network-volumes": { + "/v2/registries": { "get": { - "operationId": "listNetworkVolumes", - "summary": "List network volumes", - "description": "Returns all network volumes owned by the authenticated user.", + "operationId": "listRegistries", + "summary": "List container registries", + "description": "Returns all container registry credentials owned by the authenticated user.", "tags": [ - "Network Volumes" + "Registries" ], "responses": { "200": { @@ -4442,11 +5768,30 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ListNetworkVolumesResponse" + "$ref": "#/components/schemas/ListRegistriesResponse" + }, + "examples": { + "registries": { + "summary": "Successful response", + "value": { + "registries": [ + { + "id": "6n2k8v4d", + "name": "dockerhub-private" + } + ] + } + } } } } }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, "default": { "description": "Error", "content": { @@ -4460,18 +5805,28 @@ } }, "post": { - "operationId": "createNetworkVolume", - "summary": "Create a network volume", - "description": "Provisions a new network volume in the specified data center.", + "operationId": "createRegistry", + "summary": "Create a container registry credential", + "description": "Stores credentials for a private container registry. Credentials are write-only.", "tags": [ - "Network Volumes" + "Registries" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CreateNetworkVolumeRequest" + "$ref": "#/components/schemas/CreateRegistryRequest" + }, + "examples": { + "dockerHubRegistry": { + "summary": "Docker Hub registry", + "value": { + "name": "dockerhub-private", + "username": "runpod-user", + "password": "correct-horse-battery-staple" + } + } } } } @@ -4482,20 +5837,31 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/NetworkVolume" + "$ref": "#/components/schemas/Registry" + }, + "examples": { + "registry": { + "summary": "Successful response", + "value": { + "id": "6n2k8v4d", + "name": "dockerhub-private" + } + } } } } }, "400": { - "description": "Invalid request body", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } + "$ref": "#/components/responses/BadRequestError" + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, + "422": { + "$ref": "#/components/responses/UnprocessableEntityError" }, "default": { "description": "Error", @@ -4510,7 +5876,7 @@ } } }, - "/v2/network-volumes/{id}": { + "/v2/registries/{id}": { "parameters": [ { "name": "id", @@ -4519,16 +5885,15 @@ "schema": { "type": "string" }, - "description": "Network volume identifier", - "example": "agv6w2qcg7" + "example": "reg_abc" } ], "get": { - "operationId": "getNetworkVolume", - "summary": "Get a network volume", - "description": "Returns a single network volume by ID.", + "operationId": "getRegistry", + "summary": "Get a container registry credential", + "description": "Returns a single container registry credential by ID. `username` and\n`password` are never included in the response — credentials are\nwrite-only, matching `createRegistry`.\n", "tags": [ - "Network Volumes" + "Registries" ], "responses": { "200": { @@ -4536,20 +5901,28 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/NetworkVolume" + "$ref": "#/components/schemas/Registry" + }, + "examples": { + "registry": { + "summary": "Successful response", + "value": { + "id": "6n2k8v4d", + "name": "dockerhub-private" + } + } } } } }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, "404": { - "description": "Network volume not found", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } + "$ref": "#/components/responses/NotFoundError" }, "default": { "description": "Error", @@ -4563,36 +5936,19 @@ } } }, - "patch": { - "operationId": "updateNetworkVolume", - "summary": "Update a network volume", - "description": "Updates mutable fields on a network volume. Only provided fields are changed.\nNote: `size` may only increase; attempts to reduce size will be rejected.\n", + "delete": { + "operationId": "deleteRegistry", + "summary": "Delete a container registry credential", + "description": "Permanently deletes a container registry credential by ID. Rejected\nif any pod currently uses this credential to pull its image.\nTemplates that reference it are not part of that check — they\nsilently lose the reference (`registry` becomes null) instead of\nblocking the delete.\n", "tags": [ - "Network Volumes" + "Registries" ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/UpdateNetworkVolumeRequest" - } - } - } - }, "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/NetworkVolume" - } - } - } + "204": { + "description": "Deleted. Response has no body." }, "400": { - "description": "Invalid request body or size decrease attempted", + "description": "Registry credential is in use by a pod and cannot be deleted", "content": { "application/problem+json": { "schema": { @@ -4601,48 +5957,14 @@ } } }, - "404": { - "description": "Network volume not found", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } + "401": { + "$ref": "#/components/responses/UnauthorizedError" }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - }, - "delete": { - "operationId": "deleteNetworkVolume", - "summary": "Delete a network volume", - "description": "Permanently deletes a network volume and releases its storage.", - "tags": [ - "Network Volumes" - ], - "responses": { - "204": { - "description": "Deleted" + "403": { + "$ref": "#/components/responses/ForbiddenError" }, "404": { - "description": "Network volume not found", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } + "$ref": "#/components/responses/NotFoundError" }, "default": { "description": "Error", @@ -4657,11 +5979,10 @@ } } }, - "/v2/registries": { + "/v2/registries/delegations": { "get": { - "operationId": "listRegistries", - "summary": "List container registries", - "description": "Returns all container registry credentials owned by the authenticated user.", + "operationId": "listDelegations", + "summary": "List all ECR delegations", "tags": [ "Registries" ], @@ -4671,7 +5992,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ListRegistriesResponse" + "$ref": "#/components/schemas/ListDelegationsResponse" } } } @@ -4689,9 +6010,8 @@ } }, "post": { - "operationId": "createRegistry", - "summary": "Create a container registry credential", - "description": "Stores credentials for a private container registry. Credentials are write-only.", + "operationId": "createDelegation", + "summary": "Register an ECR delegation", "tags": [ "Registries" ], @@ -4700,18 +6020,18 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CreateRegistryRequest" + "$ref": "#/components/schemas/CreateDelegationRequest" } } } }, "responses": { "201": { - "description": "Created", + "description": "Delegation created", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Registry" + "$ref": "#/components/schemas/EcrDelegation" } } } @@ -4729,7 +6049,7 @@ } } }, - "/v2/registries/{id}": { + "/v2/registries/delegations/{id}": { "parameters": [ { "name": "id", @@ -4738,60 +6058,21 @@ "schema": { "type": "string" }, - "example": "reg_abc" + "example": "deleg_abc" } ], - "get": { - "operationId": "getRegistry", - "summary": "Get a container registry credential", - "tags": [ - "Registries" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Registry" - } - } - } - }, - "404": { - "description": "Registry not found", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - }, "delete": { - "operationId": "deleteRegistry", - "summary": "Delete a container registry credential", + "operationId": "revokeDelegation", + "summary": "Revoke an ECR delegation", "tags": [ "Registries" ], "responses": { "204": { - "description": "Deleted" + "description": "Delegation revoked" }, "404": { - "description": "Registry not found", + "description": "Delegation not found", "content": { "application/problem+json": { "schema": { @@ -4845,10 +6126,50 @@ "application/json": { "schema": { "$ref": "#/components/schemas/ListGpuTypesResponse" + }, + "examples": { + "gpus": { + "summary": "Successful response", + "value": { + "gpus": [ + { + "id": "NVIDIA GeForce RTX 4090", + "name": "RTX 4090", + "pool": "ADA_24", + "manufacturer": "NVIDIA", + "memory": 24, + "secure": true, + "community": true, + "price": { + "secure": 0.44, + "community": 0.31 + }, + "maxCount": { + "secure": 8, + "community": 4 + }, + "availability": "HIGH", + "dataCenters": [ + { + "id": "US-KS-2", + "name": "US Kansas 2", + "availability": "HIGH" + } + ] + } + ] + } + } } } } }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, "default": { "description": "Error", "content": { @@ -4905,19 +6226,48 @@ "application/json": { "schema": { "$ref": "#/components/schemas/GpuType" + }, + "examples": { + "gpu": { + "summary": "Successful response", + "value": { + "id": "NVIDIA GeForce RTX 4090", + "name": "RTX 4090", + "pool": "ADA_24", + "manufacturer": "NVIDIA", + "memory": 24, + "secure": true, + "community": true, + "price": { + "secure": 0.44, + "community": 0.31 + }, + "maxCount": { + "secure": 8, + "community": 4 + }, + "availability": "HIGH", + "dataCenters": [ + { + "id": "US-KS-2", + "name": "US Kansas 2", + "availability": "HIGH" + } + ] + } + } } } } }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, "404": { - "description": "GPU type not found", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } + "$ref": "#/components/responses/NotFoundError" }, "default": { "description": "Error", @@ -4958,10 +6308,47 @@ "application/json": { "schema": { "$ref": "#/components/schemas/ListCpuTypesResponse" + }, + "examples": { + "cpus": { + "summary": "Successful response", + "value": { + "cpus": [ + { + "id": "cpu3c-2-4", + "name": "Compute-Optimized", + "group": "Gen 3", + "vcpu": { + "min": 2, + "max": 32 + }, + "ramGbPerVcpu": 2.5, + "price": { + "securePerVcpu": 0.04, + "serverlessPerVcpu": 0.03 + }, + "availability": "MEDIUM", + "dataCenters": [ + { + "id": "US-KS-2", + "name": "US Kansas 2", + "availability": "MEDIUM" + } + ] + } + ] + } + } } } } }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, "default": { "description": "Error", "content": { @@ -5012,19 +6399,45 @@ "application/json": { "schema": { "$ref": "#/components/schemas/CpuType" + }, + "examples": { + "cpu": { + "summary": "Successful response", + "value": { + "id": "cpu3c-2-4", + "name": "Compute-Optimized", + "group": "Gen 3", + "vcpu": { + "min": 2, + "max": 32 + }, + "ramGbPerVcpu": 2.5, + "price": { + "securePerVcpu": 0.04, + "serverlessPerVcpu": 0.03 + }, + "availability": "MEDIUM", + "dataCenters": [ + { + "id": "US-KS-2", + "name": "US Kansas 2", + "availability": "MEDIUM" + } + ] + } + } } } } }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, "404": { - "description": "CPU type not found", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } + "$ref": "#/components/responses/NotFoundError" }, "default": { "description": "Error", @@ -5043,7 +6456,7 @@ "get": { "operationId": "listDataCenters", "summary": "List data centers", - "description": "Returns available data center locations.", + "description": "Returns available data center locations with region, compliance, supported network volume tiers, and global networking support. Use include=GPU_AVAILABILITY or include=CPU_AVAILABILITY to add per-resource availability arrays to each data center. The regions, networkVolumeTypes, compliance, and globalNetwork query parameters filter the list before it is returned.\n", "tags": [ "Catalog" ], @@ -5137,10 +6550,53 @@ "application/json": { "schema": { "$ref": "#/components/schemas/ListDataCentersResponse" + }, + "examples": { + "dataCenters": { + "summary": "Successful response", + "value": { + "dataCenters": [ + { + "id": "US-KS-2", + "name": "US Kansas 2", + "region": "NORTH_AMERICA", + "globalNetwork": true, + "networkVolumeTypes": [ + "STANDARD", + "HIGH_PERFORMANCE" + ], + "compliance": [ + "SOC_2_TYPE_2", + "ISO_IEC_27001" + ], + "gpuAvailability": [ + { + "id": "NVIDIA GeForce RTX 4090", + "name": "RTX 4090", + "availability": "HIGH" + } + ], + "cpuAvailability": [ + { + "id": "cpu3c-2-4", + "name": "Compute-Optimized", + "availability": "MEDIUM" + } + ] + } + ] + } + } } } } }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, "default": { "description": "Error", "content": { @@ -5199,19 +6655,51 @@ "application/json": { "schema": { "$ref": "#/components/schemas/DataCenter" + }, + "examples": { + "dataCenter": { + "summary": "Successful response", + "value": { + "id": "US-KS-2", + "name": "US Kansas 2", + "region": "NORTH_AMERICA", + "globalNetwork": true, + "networkVolumeTypes": [ + "STANDARD", + "HIGH_PERFORMANCE" + ], + "compliance": [ + "SOC_2_TYPE_2", + "ISO_IEC_27001" + ], + "gpuAvailability": [ + { + "id": "NVIDIA GeForce RTX 4090", + "name": "RTX 4090", + "availability": "HIGH" + } + ], + "cpuAvailability": [ + { + "id": "cpu3c-2-4", + "name": "Compute-Optimized", + "availability": "MEDIUM" + } + ] + } + } } } } }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, "404": { - "description": "Data center not found", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } + "$ref": "#/components/responses/NotFoundError" }, "default": { "description": "Error", @@ -5230,7 +6718,7 @@ "get": { "operationId": "listBilling", "summary": "Get aggregated billing history", - "description": "Returns time-bucketed total spend across all billable RunPod resources for the authenticated user over the requested period, with each cost component broken out.\n", + "description": "Returns time-bucketed total spend across all billable Runpod resources for the authenticated user. Use startTime/endTime with bucketSize for an explicit range, or lastN with bucketSize for the most recent buckets. Each record reports one bucket's total plus pod, serverless, storage, public endpoint, and Instant Cluster cost components. The metadata block echoes the resolved query window, record count, and totals across all returned buckets.\n", "tags": [ "Billing" ], @@ -5255,10 +6743,67 @@ "application/json": { "schema": { "$ref": "#/components/schemas/ListBillingResponse" + }, + "examples": { + "billing": { + "summary": "Successful response", + "value": { + "records": [ + { + "startTime": "2026-06-01T00:00:00Z", + "endTime": "2026-06-02T00:00:00Z", + "totalAmount": 42.34, + "podGpuAmount": 18.2, + "podCpuAmount": 0, + "podDiskAmount": 1.1, + "serverlessGpuAmount": 12.6, + "serverlessCpuAmount": 0, + "serverlessDiskAmount": 0.44, + "serverlessFeeAmount": 1.25, + "storageStandardAmount": 0, + "storageHighPerformanceAmount": 2.5, + "endpointAmount": 3.21, + "clusterGpuAmount": 2.5, + "clusterDiskAmount": 0.3, + "clusterNetworkingAmount": 0.24 + } + ], + "metadata": { + "query": { + "startTime": "2026-06-01T00:00:00Z", + "endTime": "2026-06-02T00:00:00Z", + "bucketSize": "day" + }, + "recordCount": 1, + "totals": { + "totalAmount": 42.34, + "podGpuAmount": 18.2, + "podCpuAmount": 0, + "podDiskAmount": 1.1, + "serverlessGpuAmount": 12.6, + "serverlessCpuAmount": 0, + "serverlessDiskAmount": 0.44, + "serverlessFeeAmount": 1.25, + "storageStandardAmount": 0, + "storageHighPerformanceAmount": 2.5, + "endpointAmount": 3.21, + "clusterGpuAmount": 2.5, + "clusterDiskAmount": 0.3, + "clusterNetworkingAmount": 0.24 + } + } + } + } } } } }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, "default": { "description": "Error", "content": { @@ -5276,7 +6821,7 @@ "get": { "operationId": "listPodBilling", "summary": "Get pod billing history", - "description": "Returns time-bucketed pod billing records (GPU and CPU pods) for the authenticated user over the requested period.\n", + "description": "Returns pod-only billing detail for the authenticated user, split into time buckets by startTime/endTime with bucketSize or by lastN recent buckets. Use podId to narrow the response to one GPU or CPU pod; without it, records are emitted per pod per bucket. Each record includes podId, GPU, CPU, disk, and total amounts, while metadata echoes the resolved query and totals across the pod records. Use listBilling when you need aggregate spend across every billable resource family.\n", "tags": [ "Billing" ], @@ -5311,10 +6856,50 @@ "application/json": { "schema": { "$ref": "#/components/schemas/ListPodBillingResponse" + }, + "examples": { + "podBilling": { + "summary": "Successful response", + "value": { + "records": [ + { + "startTime": "2026-06-01T00:00:00Z", + "endTime": "2026-06-02T00:00:00Z", + "podId": "7h9k2m4n6p", + "totalAmount": 12.34, + "gpuAmount": 11.1, + "cpuAmount": 0, + "diskAmount": 1.24 + } + ], + "metadata": { + "query": { + "startTime": "2026-06-01T00:00:00Z", + "endTime": "2026-06-02T00:00:00Z", + "bucketSize": "day", + "podId": "7h9k2m4n6p" + }, + "recordCount": 1, + "totals": { + "totalAmount": 12.34, + "gpuAmount": 11.1, + "cpuAmount": 0, + "diskAmount": 1.24 + }, + "uniquePodCount": 1 + } + } + } } } } }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, "default": { "description": "Error", "content": { @@ -5332,7 +6917,7 @@ "get": { "operationId": "listServerlessBilling", "summary": "Get serverless billing history", - "description": "Returns time-bucketed serverless billing records for the authenticated user over the requested period.\n", + "description": "Returns serverless endpoint billing detail for the authenticated user, split into time buckets by startTime/endTime with bucketSize or by lastN recent buckets. Use serverlessId to filter to one endpoint; without it, records are emitted per serverless endpoint per bucket. Each record reports endpoint-level GPU, CPU, disk, platform fee, and total amounts. This is distinct from pod billing, which covers standalone GPU and CPU pod costs rather than serverless endpoint workloads.\n", "tags": [ "Billing" ], @@ -5367,10 +6952,52 @@ "application/json": { "schema": { "$ref": "#/components/schemas/ListServerlessBillingResponse" + }, + "examples": { + "serverlessBilling": { + "summary": "Successful response", + "value": { + "records": [ + { + "startTime": "2026-06-01T00:00:00Z", + "endTime": "2026-06-02T00:00:00Z", + "serverlessId": "4m7x2k9q", + "totalAmount": 8.9, + "gpuAmount": 7.5, + "cpuAmount": 0, + "diskAmount": 0.4, + "feeAmount": 1 + } + ], + "metadata": { + "query": { + "startTime": "2026-06-01T00:00:00Z", + "endTime": "2026-06-02T00:00:00Z", + "bucketSize": "day", + "serverlessId": "4m7x2k9q" + }, + "recordCount": 1, + "totals": { + "totalAmount": 8.9, + "gpuAmount": 7.5, + "cpuAmount": 0, + "diskAmount": 0.4, + "feeAmount": 1 + }, + "uniqueServerlessCount": 1 + } + } + } } } } }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, "default": { "description": "Error", "content": { @@ -5388,7 +7015,7 @@ "get": { "operationId": "listEndpointBilling", "summary": "Get public endpoint billing history", - "description": "Returns time-bucketed RunPod public endpoint billing records for the authenticated user over the requested period.\n", + "description": "Returns Runpod public endpoint billing history for the authenticated user, split into time buckets by startTime/endTime with bucketSize or by lastN recent buckets. Each record reports the endpoint total for one bucket, and metadata echoes the resolved query window, record count, and total endpoint amount across all returned records.\n", "tags": [ "Billing" ], @@ -5413,10 +7040,41 @@ "application/json": { "schema": { "$ref": "#/components/schemas/ListEndpointBillingResponse" + }, + "examples": { + "endpointBilling": { + "summary": "Successful response", + "value": { + "records": [ + { + "startTime": "2026-06-01T00:00:00Z", + "endTime": "2026-06-02T00:00:00Z", + "totalAmount": 3.21 + } + ], + "metadata": { + "query": { + "startTime": "2026-06-01T00:00:00Z", + "endTime": "2026-06-02T00:00:00Z", + "bucketSize": "day" + }, + "recordCount": 1, + "totals": { + "totalAmount": 3.21 + } + } + } + } } } } }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, "default": { "description": "Error", "content": { @@ -5434,7 +7092,7 @@ "get": { "operationId": "listNetworkVolumeBilling", "summary": "Get network volume billing history", - "description": "Returns time-bucketed network volume billing records for the authenticated user over the requested period.\n", + "description": "Returns network volume billing history for the authenticated user, split into time buckets by startTime/endTime with bucketSize or by lastN recent buckets. Use networkVolumeId to filter to one volume; without it, records are emitted per volume per bucket. Each record includes standard storage, high-performance storage, and total amounts, while metadata reports the resolved query, distinct volume count, and totals across the returned records.\n", "tags": [ "Billing" ], @@ -5469,10 +7127,48 @@ "application/json": { "schema": { "$ref": "#/components/schemas/ListNetworkVolumeBillingResponse" + }, + "examples": { + "networkVolumeBilling": { + "summary": "Successful response", + "value": { + "records": [ + { + "startTime": "2026-06-01T00:00:00Z", + "endTime": "2026-06-02T00:00:00Z", + "networkVolumeId": "2q9m7x4c", + "totalAmount": 5.79, + "standardAmount": 0, + "highPerformanceAmount": 5.79 + } + ], + "metadata": { + "query": { + "startTime": "2026-06-01T00:00:00Z", + "endTime": "2026-06-02T00:00:00Z", + "bucketSize": "day", + "networkVolumeId": "2q9m7x4c" + }, + "recordCount": 1, + "totals": { + "totalAmount": 5.79, + "standardAmount": 0, + "highPerformanceAmount": 5.79 + }, + "uniqueNetworkVolumeCount": 1 + } + } + } } } } }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, "default": { "description": "Error", "content": { @@ -5490,7 +7186,7 @@ "get": { "operationId": "listClusterBilling", "summary": "Get Instant Cluster billing history", - "description": "Returns time-bucketed Instant Cluster billing records for the authenticated user over the requested period.\n", + "description": "Returns Instant Cluster billing history for the authenticated user, split into time buckets by startTime/endTime with bucketSize or by lastN recent buckets. Use clusterId to filter to one cluster; without it, records are emitted per cluster per bucket. Each record includes GPU compute, disk, inter-node networking, and total amounts. Instant Clusters are GPU-only, so no CPU cost component is returned.\n", "tags": [ "Billing" ], @@ -5525,10 +7221,50 @@ "application/json": { "schema": { "$ref": "#/components/schemas/ListClusterBillingResponse" + }, + "examples": { + "clusterBilling": { + "summary": "Successful response", + "value": { + "records": [ + { + "startTime": "2026-06-01T00:00:00Z", + "endTime": "2026-06-02T00:00:00Z", + "clusterId": "5c2n8m4q", + "totalAmount": 99, + "gpuAmount": 95, + "diskAmount": 3, + "networkingAmount": 1 + } + ], + "metadata": { + "query": { + "startTime": "2026-06-01T00:00:00Z", + "endTime": "2026-06-02T00:00:00Z", + "bucketSize": "day", + "clusterId": "5c2n8m4q" + }, + "recordCount": 1, + "totals": { + "totalAmount": 99, + "gpuAmount": 95, + "diskAmount": 3, + "networkingAmount": 1 + }, + "uniqueClusterCount": 1 + } + } + } } } } }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, "default": { "description": "Error", "content": { From 1f33e690d9af1a1526bdbeae8573a1c096392602 Mon Sep 17 00:00:00 2001 From: lgunreddi Date: Mon, 20 Jul 2026 16:28:07 -0400 Subject: [PATCH 21/41] Update docs.json --- docs.json | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs.json b/docs.json index 283a47d6..e13efc64 100644 --- a/docs.json +++ b/docs.json @@ -444,10 +444,10 @@ ] }, { - "tab": "API", + "tab": "API v1", "groups": [ { - "group": "Runpod API", + "group": "API v1", "pages": [ "api-reference/overview" ] @@ -521,10 +521,10 @@ ] }, { - "tab": "REST API (BETA)", + "tab": "API v2 (BETA)", "groups": [ { - "group": "REST API v2", + "group": "API v2", "pages": [ "api-reference-v2/overview" ] From 9680d41f1a2cfa4640acb0ea284cbbe57a332470 Mon Sep 17 00:00:00 2001 From: lgunreddi Date: Mon, 20 Jul 2026 16:29:04 -0400 Subject: [PATCH 22/41] Update overview.mdx --- api-reference-v2/overview.mdx | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/api-reference-v2/overview.mdx b/api-reference-v2/overview.mdx index a7d2b38e..0db77954 100644 --- a/api-reference-v2/overview.mdx +++ b/api-reference-v2/overview.mdx @@ -1,28 +1,27 @@ --- -title: "REST API v2" +title: "API v2" sidebarTitle: "Overview" -description: "Programmatically manage Runpod resources using the REST API v2." +description: "Programmatically manage Runpod resources using the API v2." --- - REST API v2 is currently in open beta. Endpoints and behavior may change before general availability. + API v2 is currently in beta. Endpoints and behavior may change before general availability. -The Runpod REST API v2 provides programmatic access to your Runpod resources over standard HTTP. Use it to create and manage Pods, query Serverless endpoints, provision storage, and retrieve billing data — without using the console. +The Runpod API v2 provides programmatic access to your Runpod resources over standard HTTP. Use it to create and manage Pods, query Serverless endpoints, provision storage, and retrieve billing data — without using the console. ## Base URL ``` https://api.runpod.io/v2 ``` -The Runpod REST API provides programmatic access to all Runpod compute resources. Integrate GPU infrastructure into your applications, workflows, and automation systems. +The Runpod API v2 provides programmatic access to all Runpod compute resources. Integrate GPU infrastructure into your applications, workflows, and automation systems. ## Available resources - **Pods**: Create and manage persistent GPU instances for development, training, and long-running workloads. - **Serverless**: Deploy and scale containerized applications with autoscaling and job monitoring. - **Templates**: Save and reuse Pod and endpoint configurations. -- **Tags**: Create and manage tags, and attach or detach them from resources. - **Network volumes**: Create persistent storage attachable to multiple resources. - **Container registry auth**: Connect to private Docker registries. - **Catalog**: Browse available GPU types, CPU types, and data centers. From 4bd5961f338c811f4f4681bb315559aa7763bf53 Mon Sep 17 00:00:00 2001 From: lgunreddi Date: Mon, 20 Jul 2026 16:46:14 -0400 Subject: [PATCH 23/41] Update docs.json --- docs.json | 14 +------------- 1 file changed, 1 insertion(+), 13 deletions(-) diff --git a/docs.json b/docs.json index e13efc64..3371da76 100644 --- a/docs.json +++ b/docs.json @@ -563,19 +563,7 @@ "api-reference-v2/templates/delete-a-template", "api-reference-v2/templates/update-a-template" ] - }, - { - "group": "Tags", - "pages": [ - "api-reference-v2/tags/list-tags", - "api-reference-v2/tags/create-a-tag", - "api-reference-v2/tags/get-a-tag", - "api-reference-v2/tags/delete-a-tag", - "api-reference-v2/tags/update-a-tag", - "api-reference-v2/tags/attach-a-resource-to-a-tag", - "api-reference-v2/tags/detach-a-resource-from-a-tag" - ] - }, + }, { "group": "Network Volumes", "pages": [ From bea95e8681497c2eead998ab2e3d98314e436a6e Mon Sep 17 00:00:00 2001 From: lgunreddi Date: Mon, 20 Jul 2026 16:52:51 -0400 Subject: [PATCH 24/41] Update overview.mdx --- api-reference/overview.mdx | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/api-reference/overview.mdx b/api-reference/overview.mdx index b2b2b005..9dfc944f 100644 --- a/api-reference/overview.mdx +++ b/api-reference/overview.mdx @@ -5,6 +5,10 @@ description: "Use the Runpod API to programmatically manage your compute resourc The Runpod REST API provides programmatic access to all Runpod compute resources. Integrate GPU infrastructure into your applications, workflows, and automation systems. + + **API v1 is deprecated and will be retired in the near future.** All new integrations should use [API v2](/api-reference-v2/overview) instead. + + ## Available resources - **Pods**: Create and manage persistent GPU instances for development, training, and long-running workloads. From fe1d92b94cd17fba02cf1233ae9ff7f4c0d05ec0 Mon Sep 17 00:00:00 2001 From: lgunreddi Date: Mon, 20 Jul 2026 16:54:23 -0400 Subject: [PATCH 25/41] Delete api-reference-v2/tags directory --- api-reference-v2/tags/attach-a-resource-to-a-tag.mdx | 3 --- api-reference-v2/tags/create-a-tag.mdx | 3 --- api-reference-v2/tags/delete-a-tag.mdx | 3 --- api-reference-v2/tags/detach-a-resource-from-a-tag.mdx | 3 --- api-reference-v2/tags/get-a-tag.mdx | 3 --- api-reference-v2/tags/list-tags.mdx | 3 --- api-reference-v2/tags/update-a-tag.mdx | 3 --- 7 files changed, 21 deletions(-) delete mode 100644 api-reference-v2/tags/attach-a-resource-to-a-tag.mdx delete mode 100644 api-reference-v2/tags/create-a-tag.mdx delete mode 100644 api-reference-v2/tags/delete-a-tag.mdx delete mode 100644 api-reference-v2/tags/detach-a-resource-from-a-tag.mdx delete mode 100644 api-reference-v2/tags/get-a-tag.mdx delete mode 100644 api-reference-v2/tags/list-tags.mdx delete mode 100644 api-reference-v2/tags/update-a-tag.mdx diff --git a/api-reference-v2/tags/attach-a-resource-to-a-tag.mdx b/api-reference-v2/tags/attach-a-resource-to-a-tag.mdx deleted file mode 100644 index 3c211d82..00000000 --- a/api-reference-v2/tags/attach-a-resource-to-a-tag.mdx +++ /dev/null @@ -1,3 +0,0 @@ ---- -openapi: put /v2/tags/{id}/resources/{resourceType}/{resourceId} ---- \ No newline at end of file diff --git a/api-reference-v2/tags/create-a-tag.mdx b/api-reference-v2/tags/create-a-tag.mdx deleted file mode 100644 index d9f37c8d..00000000 --- a/api-reference-v2/tags/create-a-tag.mdx +++ /dev/null @@ -1,3 +0,0 @@ ---- -openapi: post /v2/tags ---- \ No newline at end of file diff --git a/api-reference-v2/tags/delete-a-tag.mdx b/api-reference-v2/tags/delete-a-tag.mdx deleted file mode 100644 index 88ec5e8b..00000000 --- a/api-reference-v2/tags/delete-a-tag.mdx +++ /dev/null @@ -1,3 +0,0 @@ ---- -openapi: delete /v2/tags/{id} ---- \ No newline at end of file diff --git a/api-reference-v2/tags/detach-a-resource-from-a-tag.mdx b/api-reference-v2/tags/detach-a-resource-from-a-tag.mdx deleted file mode 100644 index cd42ab52..00000000 --- a/api-reference-v2/tags/detach-a-resource-from-a-tag.mdx +++ /dev/null @@ -1,3 +0,0 @@ ---- -openapi: delete /v2/tags/{id}/resources/{resourceType}/{resourceId} ---- \ No newline at end of file diff --git a/api-reference-v2/tags/get-a-tag.mdx b/api-reference-v2/tags/get-a-tag.mdx deleted file mode 100644 index 3f425172..00000000 --- a/api-reference-v2/tags/get-a-tag.mdx +++ /dev/null @@ -1,3 +0,0 @@ ---- -openapi: get /v2/tags/{id} ---- \ No newline at end of file diff --git a/api-reference-v2/tags/list-tags.mdx b/api-reference-v2/tags/list-tags.mdx deleted file mode 100644 index ef9d3372..00000000 --- a/api-reference-v2/tags/list-tags.mdx +++ /dev/null @@ -1,3 +0,0 @@ ---- -openapi: get /v2/tags ---- \ No newline at end of file diff --git a/api-reference-v2/tags/update-a-tag.mdx b/api-reference-v2/tags/update-a-tag.mdx deleted file mode 100644 index 37e77865..00000000 --- a/api-reference-v2/tags/update-a-tag.mdx +++ /dev/null @@ -1,3 +0,0 @@ ---- -openapi: patch /v2/tags/{id} ---- \ No newline at end of file From 657284dd2c94f57a54993b0c2424e72e1507e521 Mon Sep 17 00:00:00 2001 From: lgunreddi Date: Mon, 20 Jul 2026 19:30:44 -0400 Subject: [PATCH 26/41] Update docs.json --- docs.json | 90 +++---------------------------------------------------- 1 file changed, 4 insertions(+), 86 deletions(-) diff --git a/docs.json b/docs.json index 3371da76..8c476a4a 100644 --- a/docs.json +++ b/docs.json @@ -521,92 +521,10 @@ ] }, { - "tab": "API v2 (BETA)", - "groups": [ - { - "group": "API v2", - "pages": [ - "api-reference-v2/overview" - ] - }, - { - "group": "Pods", - "pages": [ - "api-reference-v2/pods/list-pods", - "api-reference-v2/pods/create-a-pod", - "api-reference-v2/pods/get-a-pod", - "api-reference-v2/pods/terminate-a-pod", - "api-reference-v2/pods/update-a-pod", - "api-reference-v2/pods/stream-pod-logs", - "api-reference-v2/pods/trigger-a-pod-state-transition" - ] - }, - { - "group": "Serverless", - "pages": [ - "api-reference-v2/serverless/list-serverless-endpoints", - "api-reference-v2/serverless/create-a-serverless-endpoint", - "api-reference-v2/serverless/get-a-serverless-endpoint", - "api-reference-v2/serverless/delete-a-serverless-endpoint", - "api-reference-v2/serverless/update-a-serverless-endpoint", - "api-reference-v2/serverless/list-serverless-endpoint-workers", - "api-reference-v2/serverless/list-serverless-endpoint-releases", - "api-reference-v2/serverless/stream-serverless-worker-logs" - ] - }, - { - "group": "Templates", - "pages": [ - "api-reference-v2/templates/list-templates", - "api-reference-v2/templates/create-a-template", - "api-reference-v2/templates/get-a-template", - "api-reference-v2/templates/delete-a-template", - "api-reference-v2/templates/update-a-template" - ] - }, - { - "group": "Network Volumes", - "pages": [ - "api-reference-v2/network-volumes/list-network-volumes", - "api-reference-v2/network-volumes/create-a-network-volume", - "api-reference-v2/network-volumes/get-a-network-volume", - "api-reference-v2/network-volumes/delete-a-network-volume", - "api-reference-v2/network-volumes/update-a-network-volume" - ] - }, - { - "group": "Registries", - "pages": [ - "api-reference-v2/registries/list-container-registries", - "api-reference-v2/registries/create-a-container-registry-credential", - "api-reference-v2/registries/get-a-container-registry-credential", - "api-reference-v2/registries/delete-a-container-registry-credential" - ] - }, - { - "group": "Catalog", - "pages": [ - "api-reference-v2/catalog/list-gpu-types", - "api-reference-v2/catalog/get-a-gpu-type", - "api-reference-v2/catalog/list-cpu-types", - "api-reference-v2/catalog/get-a-cpu-type", - "api-reference-v2/catalog/list-data-centers", - "api-reference-v2/catalog/get-a-data-center" - ] - }, - { - "group": "Billing", - "pages": [ - "api-reference-v2/billing/get-aggregated-billing-history", - "api-reference-v2/billing/get-pod-billing-history", - "api-reference-v2/billing/get-serverless-billing-history", - "api-reference-v2/billing/get-public-endpoint-billing-history", - "api-reference-v2/billing/get-network-volume-billing-history", - "api-reference-v2/billing/get-instant-cluster-billing-history" - ] - } - ] -}, + "tab": "API v2 (BETA)", + "pages": ["api-reference-v2/overview"], + "openapi": "api-reference-v2/openapi.json" + }, { "tab": "Models", "groups": [ From ab0a020de390512a4c13adf9866bbaeb21a1e887 Mon Sep 17 00:00:00 2001 From: lgunreddi Date: Mon, 20 Jul 2026 19:40:00 -0400 Subject: [PATCH 27/41] Update docs.json --- docs.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs.json b/docs.json index 8c476a4a..7a0f3d39 100644 --- a/docs.json +++ b/docs.json @@ -522,7 +522,7 @@ }, { "tab": "API v2 (BETA)", - "pages": ["api-reference-v2/overview"], + "root": "api-reference-v2/overview", "openapi": "api-reference-v2/openapi.json" }, { From 0e81b7c30192d3264f4f35aa1f3f504d2be4fa62 Mon Sep 17 00:00:00 2001 From: lgunreddi Date: Mon, 20 Jul 2026 19:47:01 -0400 Subject: [PATCH 28/41] Update docs.json --- docs.json | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/docs.json b/docs.json index 7a0f3d39..a1aefc54 100644 --- a/docs.json +++ b/docs.json @@ -521,9 +521,14 @@ ] }, { - "tab": "API v2 (BETA)", - "root": "api-reference-v2/overview", - "openapi": "api-reference-v2/openapi.json" + { + "tab": "API v2 (BETA)", + "root": "api-reference-v2/overview", + "openapi": { + "source": "api-reference-v2/openapi.json", + "directory": "api-reference-v2" + } + } }, { "tab": "Models", From 7e8ba29ed3a57926f205d2f16b90f4bf81492d41 Mon Sep 17 00:00:00 2001 From: lgunreddi Date: Mon, 20 Jul 2026 20:03:27 -0400 Subject: [PATCH 29/41] Update docs.json --- docs.json | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/docs.json b/docs.json index a1aefc54..8eb33ffd 100644 --- a/docs.json +++ b/docs.json @@ -521,13 +521,11 @@ ] }, { - { - "tab": "API v2 (BETA)", - "root": "api-reference-v2/overview", - "openapi": { + "tab": "API v2 (BETA)", + "root": "api-reference-v2/overview", + "openapi": { "source": "api-reference-v2/openapi.json", "directory": "api-reference-v2" - } } }, { From d3436d0f32b9708bac34ef9ca10b6098a9ed862e Mon Sep 17 00:00:00 2001 From: lgunreddi Date: Tue, 21 Jul 2026 08:28:53 -0400 Subject: [PATCH 30/41] Update docs.json --- docs.json | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/docs.json b/docs.json index 8eb33ffd..1771c803 100644 --- a/docs.json +++ b/docs.json @@ -522,12 +522,20 @@ }, { "tab": "API v2 (BETA)", - "root": "api-reference-v2/overview", - "openapi": { + "groups": [ + { + "group": "Overview", + "pages": ["api-reference-v2/overview"] + }, + { + "group": "API v2 (BETA)", + "openapi": { "source": "api-reference-v2/openapi.json", "directory": "api-reference-v2" - } - }, + } + } + ] + }, { "tab": "Models", "groups": [ From 0a501f22aaf0987784880131b42e52968a8ace76 Mon Sep 17 00:00:00 2001 From: lgunreddi Date: Tue, 21 Jul 2026 08:48:52 -0400 Subject: [PATCH 31/41] Update docs.json --- docs.json | 89 +++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 80 insertions(+), 9 deletions(-) diff --git a/docs.json b/docs.json index 1771c803..3c80213f 100644 --- a/docs.json +++ b/docs.json @@ -523,18 +523,89 @@ { "tab": "API v2 (BETA)", "groups": [ + { + "group": "API v2", + "pages": [ + "api-reference-v2/overview" + ] + }, { - "group": "Overview", - "pages": ["api-reference-v2/overview"] + "group": "Pods", + "pages": [ + "api-reference-v2/pods/list-pods", + "api-reference-v2/pods/create-a-pod", + "api-reference-v2/pods/get-a-pod", + "api-reference-v2/pods/terminate-a-pod", + "api-reference-v2/pods/update-a-pod", + "api-reference-v2/pods/stream-pod-logs", + "api-reference-v2/pods/trigger-a-pod-state-transition" + ] }, { - "group": "API v2 (BETA)", - "openapi": { - "source": "api-reference-v2/openapi.json", - "directory": "api-reference-v2" - } - } - ] + "group": "Serverless", + "pages": [ + "api-reference-v2/serverless/list-serverless-endpoints", + "api-reference-v2/serverless/create-a-serverless-endpoint", + "api-reference-v2/serverless/get-a-serverless-endpoint", + "api-reference-v2/serverless/delete-a-serverless-endpoint", + "api-reference-v2/serverless/update-a-serverless-endpoint", + "api-reference-v2/serverless/list-serverless-endpoint-workers", + "api-reference-v2/serverless/list-serverless-endpoint-releases", + "api-reference-v2/serverless/stream-serverless-worker-logs" + ] + }, + { + "group": "Templates", + "pages": [ + "api-reference-v2/templates/list-templates", + "api-reference-v2/templates/create-a-template", + "api-reference-v2/templates/get-a-template", + "api-reference-v2/templates/delete-a-template", + "api-reference-v2/templates/update-a-template" + ] + }, + { + "group": "Network Volumes", + "pages": [ + "api-reference-v2/network-volumes/list-network-volumes", + "api-reference-v2/network-volumes/create-a-network-volume", + "api-reference-v2/network-volumes/get-a-network-volume", + "api-reference-v2/network-volumes/delete-a-network-volume", + "api-reference-v2/network-volumes/update-a-network-volume" + ] + }, + { + "group": "Registries", + "pages": [ + "api-reference-v2/registries/list-container-registries", + "api-reference-v2/registries/create-a-container-registry-credential", + "api-reference-v2/registries/get-a-container-registry-credential", + "api-reference-v2/registries/delete-a-container-registry-credential" + ] + }, + { + "group": "Catalog", + "pages": [ + "api-reference-v2/catalog/list-gpu-types", + "api-reference-v2/catalog/get-a-gpu-type", + "api-reference-v2/catalog/list-cpu-types", + "api-reference-v2/catalog/get-a-cpu-type", + "api-reference-v2/catalog/list-data-centers", + "api-reference-v2/catalog/get-a-data-center" + ] + }, + { + "group": "Billing", + "pages": [ + "api-reference-v2/billing/get-aggregated-billing-history", + "api-reference-v2/billing/get-pod-billing-history", + "api-reference-v2/billing/get-serverless-billing-history", + "api-reference-v2/billing/get-public-endpoint-billing-history", + "api-reference-v2/billing/get-network-volume-billing-history", + "api-reference-v2/billing/get-instant-cluster-billing-history" + ] + } + ] }, { "tab": "Models", From 1330fcd88a91914ac8740839f04fcb2adeec288c Mon Sep 17 00:00:00 2001 From: lgunreddi Date: Wed, 22 Jul 2026 10:43:36 -0400 Subject: [PATCH 32/41] Update overview.mdx --- api-reference-v2/overview.mdx | 7512 ++++++++++++++++++++++++++++++++- 1 file changed, 7457 insertions(+), 55 deletions(-) diff --git a/api-reference-v2/overview.mdx b/api-reference-v2/overview.mdx index 0db77954..cb08c0a1 100644 --- a/api-reference-v2/overview.mdx +++ b/api-reference-v2/overview.mdx @@ -1,55 +1,7457 @@ ---- -title: "API v2" -sidebarTitle: "Overview" -description: "Programmatically manage Runpod resources using the API v2." ---- - - - API v2 is currently in beta. Endpoints and behavior may change before general availability. - - -The Runpod API v2 provides programmatic access to your Runpod resources over standard HTTP. Use it to create and manage Pods, query Serverless endpoints, provision storage, and retrieve billing data — without using the console. - -## Base URL - -``` -https://api.runpod.io/v2 -``` -The Runpod API v2 provides programmatic access to all Runpod compute resources. Integrate GPU infrastructure into your applications, workflows, and automation systems. - -## Available resources - -- **Pods**: Create and manage persistent GPU instances for development, training, and long-running workloads. -- **Serverless**: Deploy and scale containerized applications with autoscaling and job monitoring. -- **Templates**: Save and reuse Pod and endpoint configurations. -- **Network volumes**: Create persistent storage attachable to multiple resources. -- **Container registry auth**: Connect to private Docker registries. -- **Catalog**: Browse available GPU types, CPU types, and data centers. -- **Billing**: Access usage metrics and billing information. - -## Authentication - -All requests require a [Runpod API key](/get-started/api-keys) in the request headers. The API uses standard HTTP methods and returns JSON responses. - -## OpenAPI schema - -Retrieve the complete OpenAPI specification for client generation, request validation, or tooling integration. - - - -```bash cURL -curl --request GET \ - --url https://api.runpod.io/v2/openapi.json \ - --header 'Authorization: Bearer RUNPOD_API_KEY' -``` - -```python Python -import requests - -url = "https://api.runpod.io/v2/openapi.json" -headers = {"Authorization": "Bearer RUNPOD_API_KEY"} -response = requests.get(url, headers=headers) -print(response.json()) -``` - - +{ + "openapi": "3.1.0", + "info": { + "title": "Runpod REST API", + "version": "2.0.0", + "description": "Runpod public REST API — v2" + }, + "servers": [ + { + "url": "https://api.runpod.io", + "description": "Runpod API v2 production server" + } + ], + "security": [ + { + "bearerAuth": [] + } + ], + "tags": [ + { + "name": "Pods", + "description": "GPU and CPU pod lifecycle, configuration, actions, and log streaming." + }, + { + "name": "Serverless", + "description": "Serverless endpoint lifecycle, worker visibility, releases, and worker log streaming." + }, + { + "name": "Templates", + "description": "Reusable pod and endpoint configuration templates." + }, + { + "name": "Network Volumes", + "description": "Persistent network storage volumes for workloads." + }, + { + "name": "Registries", + "description": "Container registry credentials used to pull private images." + }, + { + "name": "Catalog", + "description": "Available GPU, CPU, and data center catalog metadata." + }, + { + "name": "Billing", + "description": "Billing history and usage cost records across resource types." + } + ], + "components": { + "securitySchemes": { + "bearerAuth": { + "type": "http", + "scheme": "bearer", + "bearerFormat": "Runpod API Key", + "description": "Runpod API key authentication. Generate an API key in the Runpod console and send it in the `Authorization` header as `Bearer `. Keys are scoped to the permissions granted when created; requests may return `403` when a valid key lacks access to the requested resource or action.\n" + } + }, + "responses": { + "UnauthorizedError": { + "description": "Authentication failed because the bearer token is missing, malformed, expired, or invalid.", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + }, + "examples": { + "missingBearerToken": { + "summary": "Missing bearer token", + "value": { + "title": "Unauthorized", + "status": 401, + "detail": "missing bearer token" + } + } + } + } + } + }, + "ForbiddenError": { + "description": "The bearer token is valid, but it does not grant access to the requested resource or action.", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + }, + "examples": { + "insufficientAccess": { + "summary": "Insufficient access", + "value": { + "title": "Forbidden", + "status": 403, + "detail": "access denied" + } + } + } + } + } + }, + "BadRequestError": { + "description": "The request could not be processed because it is malformed or conflicts with request rules.", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + }, + "examples": { + "badRequest": { + "summary": "Bad request", + "value": { + "title": "Bad Request", + "status": 400, + "detail": "request could not be processed" + } + } + } + } + } + }, + "NotFoundError": { + "description": "The requested resource was not found or is not accessible to the caller.", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + }, + "examples": { + "notFound": { + "summary": "Resource not found", + "value": { + "title": "Not Found", + "status": 404, + "detail": "resource not found" + } + } + } + } + } + }, + "UnprocessableEntityError": { + "description": "The request body or parameters were syntactically valid but failed validation.", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + }, + "examples": { + "validationFailed": { + "summary": "Validation failed", + "value": { + "title": "Unprocessable Entity", + "status": 422, + "detail": "Request validation failed." + } + } + } + } + } + }, + "MethodNotAllowedError": { + "description": "The request method is not supported for the target path.", + "headers": { + "Allow": { + "description": "Comma-separated methods supported by the target path.", + "schema": { + "type": "string" + }, + "example": "GET, POST" + } + }, + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + }, + "examples": { + "methodNotAllowed": { + "summary": "Method not allowed", + "value": { + "title": "Method Not Allowed", + "status": 405, + "detail": "The requested method is not allowed for this path." + } + } + } + } + } + }, + "TooManyRequestsError": { + "description": "The caller exceeded its per-user rate limit. The response identifies the window that was exceeded and how long to wait. The `RateLimit` and `RateLimit-Policy` headers (per the IETF ratelimit-headers draft) also accompany successful responses, so clients can track quota before a 429.\n", + "headers": { + "Retry-After": { + "description": "Seconds to wait before retrying, per the exceeded window.", + "schema": { + "type": "integer" + }, + "example": 12 + }, + "RateLimit": { + "description": "Live per-window state as a structured-field list — one member per window (`minute`, `hour`, `day`) with remaining count `r` and seconds-until-reset `t`.\n", + "schema": { + "type": "string" + }, + "example": "\"minute\";r=0;t=12, \"hour\";r=2800;t=1812, \"day\";r=49500;t=45012" + }, + "RateLimit-Policy": { + "description": "Static quota policy as a structured-field list — one member per window with quota `q` and window length `w` (seconds).\n", + "schema": { + "type": "string" + }, + "example": "\"minute\";q=60;w=60, \"hour\";q=3000;w=3600, \"day\";q=50000;w=86400" + } + }, + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + }, + "examples": { + "rateLimited": { + "summary": "Rate limit exceeded", + "value": { + "title": "Too Many Requests", + "status": 429, + "detail": "rate limit exceeded for the minute window" + } + } + } + } + } + } + }, + "parameters": { + "BillingStartTime": { + "name": "startTime", + "in": "query", + "required": false, + "description": "Start of the billing period (RFC 3339). Defaults to 30 days ago. Snapped down to the start of its bucketSize bucket so the window aligns with the returned records; provide a boundary-aligned value (e.g. midnight for bucketSize=day) to avoid widening.\n", + "schema": { + "type": "string", + "format": "date-time" + }, + "example": "2026-05-01T00:00:00Z" + }, + "BillingEndTime": { + "name": "endTime", + "in": "query", + "required": false, + "description": "End of the billing period (RFC 3339), exclusive. Defaults to now. Snapped up to the end of the bucketSize bucket it lands in (unless already on a boundary) so the window aligns with the returned records.\n", + "schema": { + "type": "string", + "format": "date-time" + }, + "example": "2026-06-01T00:00:00Z" + }, + "BillingBucketSize": { + "name": "bucketSize", + "in": "query", + "required": false, + "description": "Length of each billing time bucket. Defaults to day.", + "schema": { + "$ref": "#/components/schemas/BillingBucketSize" + } + }, + "BillingLastN": { + "name": "lastN", + "in": "query", + "required": false, + "description": "Return the last N buckets of bucketSize, ending with the current (in-progress) bucket — e.g. lastN=100 with bucketSize=day is \"last 100 days\". The resolved window is aligned to bucket boundaries: startTime is the start of the earliest bucket (e.g. midnight of the earliest day) and endTime is the end of the current bucket. Mutually exclusive with startTime/endTime; provide one or the other, not both.\n", + "schema": { + "type": "integer", + "minimum": 1 + }, + "example": 30 + }, + "CatalogIncludeParam": { + "name": "include", + "in": "query", + "required": false, + "description": "Comma-separated optional expansions. Supported value today: AVAILABILITY. This may expand with more include values in the future.", + "style": "form", + "explode": false, + "schema": { + "type": "array", + "maxItems": 1, + "items": { + "$ref": "#/components/schemas/CatalogInclude" + } + }, + "example": [ + "AVAILABILITY" + ] + }, + "GpuProductFilter": { + "name": "product", + "in": "query", + "required": false, + "description": "Comma-separated availability product contexts. Supported values: POD, CLUSTER, SERVERLESS. Valid only with include=AVAILABILITY. Upstream default when omitted: POD.", + "style": "form", + "explode": false, + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Product" + } + }, + "example": [ + "POD", + "SERVERLESS" + ] + }, + "GpuCountFilter": { + "name": "count", + "in": "query", + "required": false, + "description": "GPU count for availability and lowest-price calculations. Valid only with include=AVAILABILITY. Defaults to 1.", + "schema": { + "type": "integer", + "minimum": 1, + "default": 1 + }, + "example": 2 + }, + "GpuCloudFilter": { + "name": "cloud", + "in": "query", + "required": false, + "description": "Cloud type for availability and lowest-price calculations. Valid only with include=AVAILABILITY. Supported values: SECURE, COMMUNITY. Upstream default when omitted: SECURE.", + "schema": { + "$ref": "#/components/schemas/GpuCloudFilter" + } + }, + "MinCudaVersionFilter": { + "name": "minCudaVersion", + "in": "query", + "required": false, + "description": "Minimum CUDA version for availability and lowest-price calculations. Valid only with include=AVAILABILITY. Format: integer major or major.minor, e.g. 12 or 12.1.", + "schema": { + "type": "string" + }, + "example": "12.1" + }, + "CpuProductFilter": { + "name": "product", + "in": "query", + "required": false, + "description": "Comma-separated availability product context. Valid only with include=AVAILABILITY. Supported values for CPUs: POD, SERVERLESS. Defaults to POD when omitted.", + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CpuProduct" + }, + "example": [ + "POD", + "SERVERLESS" + ] + } + }, + "CpuVCPUCountFilter": { + "name": "vcpuCount", + "in": "query", + "required": false, + "description": "Availability vCPU count. Valid only with include=AVAILABILITY. Must be a power of two.", + "schema": { + "type": "integer", + "minimum": 2 + }, + "example": 4 + }, + "LogSourceParam": { + "name": "source", + "in": "query", + "required": false, + "description": "Log source to stream. Omit to include both container and system logs.", + "schema": { + "$ref": "#/components/schemas/LogSource" + } + }, + "LogTail": { + "name": "tail", + "in": "query", + "required": false, + "description": "Number of historical lines to backfill before streaming. Defaults to\n100 when omitted; set `0` to stream live with no backfill. Maximum 5000.\nIgnored when `since` or `Last-Event-ID` is provided — the resume cursor\ndrives the backfill instead.\n", + "schema": { + "type": "integer", + "minimum": 0, + "maximum": 5000, + "default": 100 + } + }, + "LogSince": { + "name": "since", + "in": "query", + "required": false, + "description": "RFC3339 timestamp to resume from. Ignored when `Last-Event-ID` is\nprovided. When set, the stream resumes from this point and `tail` is\nignored.\n", + "schema": { + "type": "string", + "format": "date-time" + } + }, + "LogLastEventID": { + "name": "Last-Event-ID", + "in": "header", + "required": false, + "description": "SSE reconnect cursor — a timestamp emitted by this endpoint. Takes\nprecedence over `since` and `tail`: when present, the stream resumes\nfrom this point. Sent automatically by EventSource on reconnect.\n", + "schema": { + "type": "string", + "format": "date-time" + } + } + }, + "schemas": { + "ContainerConfig": { + "type": "object", + "description": "Reusable container configuration shared across templates, pods, and serverless endpoints. Adding a field here automatically propagates to all three resources.\n", + "properties": { + "image": { + "type": "string", + "description": "Docker image reference", + "examples": [ + "runpod/pytorch:2.8.0-py3.11-cuda12.8.1" + ] + }, + "args": { + "type": "string", + "description": "Arguments passed to the container entrypoint", + "examples": [ + "" + ] + }, + "disk": { + "type": "integer", + "minimum": 1, + "description": "Container disk in GB (ephemeral, wiped on restart)", + "examples": [ + 50 + ] + }, + "ports": { + "type": "array", + "description": "Exposed ports, formatted as port/protocol", + "items": { + "type": "string" + }, + "examples": [ + [ + "8888/http", + "22/tcp" + ] + ] + }, + "env": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "Environment variables as key-value pairs", + "examples": [ + { + "JUPYTER_PASSWORD": "hunter2" + } + ] + }, + "registry": { + "type": [ + "string", + "null" + ], + "description": "Container registry credential ID (for private images)", + "examples": [ + null + ] + } + } + }, + "Mounts": { + "type": "object", + "additionalProperties": false, + "description": "Storage mounts attached to a pod. At-most-one of `persistent` or\n`network` may be set today (mutually exclusive, enforced at the\nhandler with 400 if both are present). The `network` field is an\narray for forward compatibility with eventual multi-network-volume\nsupport, but `maxItems` is 1 today.\n\nPATCH semantics:\n- Omitting `mounts` or sending `{}` leaves the existing mount\n unchanged.\n- An explicit `network: []` is rejected with 400 (clearing mounts\n is not supported).\n- Mount kind is fixed at create — a PATCH that introduces a kind\n not present at create (persistent on a network pod, network on\n a persistent pod, or any mount on a previously-mountless pod)\n is rejected with 400.\n- The `volumeId` of a network mount is immutable; a PATCH that\n names a different `volumeId` is rejected with 400.\n- Partial mounts are not supported — every mount entry must\n include the full schema (`size` + `path` for persistent,\n `volumeId` + `path` for network). Missing required fields → 422.\n", + "properties": { + "persistent": { + "$ref": "#/components/schemas/PersistentMount" + }, + "network": { + "type": "array", + "maxItems": 1, + "items": { + "$ref": "#/components/schemas/NetworkMount" + } + } + } + }, + "TemplateMounts": { + "type": "object", + "additionalProperties": false, + "description": "Storage mounts attached to a template. Templates support only a\nsingle persistent mount today; any `network` property is rejected\nwith 422 by the schema validator.\n\nPATCH semantics: omitting `mounts` or sending `{}` leaves the\nexisting mount unchanged.\n", + "properties": { + "persistent": { + "$ref": "#/components/schemas/PersistentMount" + } + } + }, + "PersistentMount": { + "type": "object", + "required": [ + "size", + "path" + ], + "additionalProperties": false, + "description": "Host-local persistent storage. Pinned to the pod's host machine — data\ndoes not survive a host failure. Disallowed on CPU pods. Mutually\nexclusive with NetworkMount. Deprecated: prefer NetworkMount for any\ndata you cannot recreate.\n", + "properties": { + "size": { + "type": "integer", + "minimum": 10, + "description": "Host-local persistent storage in GB. Upstream enforces a 10 GB floor.", + "examples": [ + 20 + ] + }, + "path": { + "type": "string", + "description": "Mount path inside the container. May be changed via PATCH.", + "examples": [ + "/workspace" + ] + } + } + }, + "NetworkMount": { + "type": "object", + "required": [ + "volumeId", + "path" + ], + "additionalProperties": false, + "description": "Reference to a NetworkVolume. Custom paths are honored at runtime on\nboth GPU and CPU pods. The underlying `volumeId` is immutable\npost-create; the mount `path` may be changed via PATCH.\n", + "properties": { + "volumeId": { + "type": "string", + "description": "ID of an existing NetworkVolume in the same data center as the pod.", + "examples": [ + "vol_xyz" + ] + }, + "path": { + "type": "string", + "description": "Mount path inside the container. No default — must be specified explicitly.", + "examples": [ + "/runpod-volume" + ] + } + } + }, + "GpuConfig": { + "type": "object", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "string", + "description": "GPU type identifier", + "examples": [ + "NVIDIA GeForce RTX 4090" + ] + }, + "count": { + "type": "integer", + "minimum": 1, + "default": 1, + "description": "Number of GPUs", + "examples": [ + 1 + ] + } + } + }, + "BaseCpuConfig": { + "type": "object", + "required": [ + "id", + "vcpuCount" + ], + "properties": { + "id": { + "type": "string", + "description": "CPU flavor identifier, as returned by GET /v2/catalog/cpus.", + "examples": [ + "cpu5c" + ], + "minLength": 1 + }, + "vcpuCount": { + "type": "integer", + "minimum": 2, + "description": "Number of vCPUs. Must be valid for the selected CPU flavor and must be a power of two.", + "examples": [ + 4 + ] + } + } + }, + "CreateCpuConfig": { + "allOf": [ + { + "$ref": "#/components/schemas/BaseCpuConfig" + } + ], + "unevaluatedProperties": false + }, + "CpuConfig": { + "allOf": [ + { + "$ref": "#/components/schemas/BaseCpuConfig" + }, + { + "type": "object", + "required": [ + "memory" + ], + "properties": { + "memory": { + "type": "integer", + "minimum": 1, + "description": "Memory allocated to the pod in GB.", + "examples": [ + 16 + ] + } + } + } + ] + }, + "ScalerType": { + "type": "string", + "description": "Autoscaling strategy.\n- `QUEUE_DELAY` — scale on seconds a request waits in queue\n- `REQUEST_COUNT` — scale on in-flight request count\n", + "enum": [ + "QUEUE_DELAY", + "REQUEST_COUNT" + ] + }, + "FlashBoot": { + "type": "string", + "description": "FlashBoot cold-start acceleration mode.\n- `OFF` — disabled\n- `FLASHBOOT` — enabled\n- `PRIORITY_FLASHBOOT` — enabled with priority capacity\n", + "enum": [ + "OFF", + "FLASHBOOT", + "PRIORITY_FLASHBOOT" + ] + }, + "EndpointType": { + "type": "string", + "description": "Request-routing semantics for a modern serverless endpoint.\n- `QUEUE_BASED` — submit asynchronous or synchronous jobs through the managed queue.\n- `LOAD_BALANCING` — send requests directly to worker-defined HTTP paths.\n", + "x-enum-varnames": [ + "EndpointTypeQueueBased", + "EndpointTypeLoadBalancing" + ], + "enum": [ + "QUEUE_BASED", + "LOAD_BALANCING" + ] + }, + "QueueBasedRequestUrls": { + "type": "object", + "additionalProperties": false, + "required": [ + "run", + "runSync" + ], + "properties": { + "run": { + "type": "string", + "format": "uri", + "description": "URL for asynchronously submitting a queued job.", + "examples": [ + "https://api.runpod.ai/v2/4m7x2k9q/run" + ] + }, + "runSync": { + "type": "string", + "format": "uri", + "description": "URL for synchronously submitting a queued job.", + "examples": [ + "https://api.runpod.ai/v2/4m7x2k9q/runsync" + ] + } + } + }, + "LoadBalancingRequestUrls": { + "type": "object", + "additionalProperties": false, + "required": [ + "base" + ], + "properties": { + "base": { + "type": "string", + "format": "uri", + "description": "Base URL for worker-defined HTTP and WebSocket paths.", + "examples": [ + "https://4m7x2k9q.api.runpod.ai" + ] + } + } + }, + "EndpointRequestUrls": { + "description": "Request submission URLs appropriate to the endpoint's top-level `type`.\nQueue-based endpoints provide `run` and `runSync`; load-balancing\nendpoints provide `base` because their paths are worker-defined.\n", + "oneOf": [ + { + "$ref": "#/components/schemas/QueueBasedRequestUrls" + }, + { + "$ref": "#/components/schemas/LoadBalancingRequestUrls" + } + ] + }, + "EndpointGpuConfig": { + "type": "object", + "required": [ + "pools" + ], + "properties": { + "pools": { + "type": "array", + "minItems": 1, + "description": "Serverless GPU pool IDs (as returned by `GET /v2/catalog/gpus` in\n`pool`). Workers are placed on whichever listed pool has capacity.\n", + "items": { + "type": "string" + }, + "examples": [ + [ + "ADA_24" + ] + ] + }, + "count": { + "type": "integer", + "minimum": 1, + "default": 1, + "description": "GPUs per worker", + "examples": [ + 1 + ] + } + } + }, + "Endpoint": { + "allOf": [ + { + "$ref": "#/components/schemas/ContainerConfig" + }, + { + "type": "object", + "required": [ + "id", + "name", + "workers", + "scaling", + "dataCenterIds", + "networkVolumes", + "timeout", + "flashboot", + "createdAt" + ], + "properties": { + "id": { + "type": "string", + "examples": [ + "ep_abc123" + ] + }, + "name": { + "type": "string", + "examples": [ + "my-inference" + ] + }, + "type": { + "$ref": "#/components/schemas/EndpointType" + }, + "requestUrls": { + "$ref": "#/components/schemas/EndpointRequestUrls" + }, + "gpu": { + "anyOf": [ + { + "$ref": "#/components/schemas/EndpointGpuConfig" + }, + { + "type": "null" + } + ] + }, + "cpu": { + "description": "Read-only. Present for CPU serverless endpoints; CPU create/update is not yet supported.", + "anyOf": [ + { + "$ref": "#/components/schemas/CpuConfig" + }, + { + "type": "null" + } + ] + }, + "workers": { + "type": "object", + "required": [ + "min", + "max" + ], + "properties": { + "min": { + "type": "integer", + "minimum": 0, + "examples": [ + 0 + ] + }, + "max": { + "type": "integer", + "minimum": 0, + "examples": [ + 5 + ] + } + } + }, + "scaling": { + "type": "object", + "required": [ + "type", + "value", + "idleTimeout" + ], + "properties": { + "type": { + "$ref": "#/components/schemas/ScalerType" + }, + "value": { + "type": "number", + "format": "float", + "minimum": 0.5, + "examples": [ + 4 + ] + }, + "idleTimeout": { + "type": "integer", + "minimum": 0, + "description": "Seconds before idle workers scale down", + "examples": [ + 5 + ] + } + } + }, + "dataCenterIds": { + "type": "array", + "items": { + "type": "string" + }, + "examples": [ + [ + "US-TX-3" + ] + ] + }, + "networkVolumes": { + "type": "array", + "items": { + "type": "string" + }, + "examples": [ + [ + "vol_abc" + ] + ] + }, + "timeout": { + "type": "integer", + "description": "Per-request execution timeout in milliseconds", + "examples": [ + 300000 + ] + }, + "flashboot": { + "$ref": "#/components/schemas/FlashBoot" + }, + "createdAt": { + "type": "string", + "format": "date-time", + "examples": [ + "2026-03-13T20:00:00Z" + ] + } + } + } + ] + }, + "ListEndpointsResponse": { + "type": "object", + "required": [ + "endpoints" + ], + "properties": { + "endpoints": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Endpoint" + } + } + } + }, + "WorkerStatus": { + "type": "string", + "description": "Derived worker state, reconciled from the worker pod's lifecycle status\nand the live job-queue view.\n- `RUNNING` — actively processing a job\n- `IDLE` — ready and polling for jobs\n- `INITIALIZING` — starting up, not yet ready\n- `THROTTLED` — waiting on compute capacity\n- `UNHEALTHY` — failing health checks\n", + "x-enum-varnames": [ + "WorkerStatusRunning", + "WorkerStatusIdle", + "WorkerStatusInitializing", + "WorkerStatusThrottled", + "WorkerStatusUnhealthy" + ], + "enum": [ + "RUNNING", + "IDLE", + "INITIALIZING", + "THROTTLED", + "UNHEALTHY" + ] + }, + "Worker": { + "type": "object", + "required": [ + "id", + "status", + "gpuCount", + "isStale" + ], + "properties": { + "id": { + "type": "string", + "examples": [ + "worker_abc" + ] + }, + "status": { + "$ref": "#/components/schemas/WorkerStatus" + }, + "isStale": { + "type": "boolean", + "description": "True when the worker is running an older endpoint configuration than\nthe current one (e.g. mid rolling-update). This is the authoritative\nflag: it is derived from `version` vs the response's `endpointVersion`,\nexcept on legacy endpoints (`endpointVersion` 1) where it falls back\nto a container-image comparison.\n", + "examples": [ + false + ] + }, + "version": { + "type": [ + "integer", + "null" + ], + "description": "Endpoint configuration version this worker is running. Compare with\nthe response's `endpointVersion`. Null if unknown.\n", + "examples": [ + 4 + ] + }, + "gpuCount": { + "type": "integer", + "minimum": 0, + "description": "GPUs allocated to the worker.", + "examples": [ + 1 + ] + }, + "image": { + "type": [ + "string", + "null" + ], + "description": "Container image the worker is running.", + "examples": [ + "my-org/sdxl-worker:latest" + ] + }, + "uptimeSeconds": { + "type": [ + "integer", + "null" + ], + "minimum": 0, + "description": "Seconds the worker has been running. Null until the worker is placed and running.", + "examples": [ + 3600 + ] + }, + "gpuTypeId": { + "type": [ + "string", + "null" + ], + "description": "GPU type the worker is placed on. Null until the worker is placed.", + "examples": [ + "NVIDIA RTX 4090" + ] + }, + "dataCenterId": { + "type": [ + "string", + "null" + ], + "description": "Data center the worker is placed in. Null until the worker is placed.", + "examples": [ + "US-TX-3" + ] + }, + "startedAt": { + "type": [ + "string", + "null" + ], + "format": "date-time", + "description": "When the worker last started. Null if it has not started.", + "examples": [ + "2026-03-26T00:00:00Z" + ] + } + } + }, + "WorkerSummary": { + "type": "object", + "description": "Histogram of the returned workers by status. The per-status counts are a\nroll-up of the `workers` array, so `running + idle + initializing +\nthrottled + unhealthy == total == len(workers)`.\n", + "required": [ + "running", + "idle", + "initializing", + "throttled", + "unhealthy", + "total" + ], + "properties": { + "running": { + "type": "integer", + "minimum": 0, + "description": "Workers actively processing a job.", + "examples": [ + 2 + ] + }, + "idle": { + "type": "integer", + "minimum": 0, + "description": "Ready workers polling for jobs.", + "examples": [ + 1 + ] + }, + "initializing": { + "type": "integer", + "minimum": 0, + "description": "Workers starting up, not yet ready.", + "examples": [ + 0 + ] + }, + "throttled": { + "type": "integer", + "minimum": 0, + "description": "Workers waiting on compute capacity.", + "examples": [ + 0 + ] + }, + "unhealthy": { + "type": "integer", + "minimum": 0, + "description": "Workers failing health checks.", + "examples": [ + 0 + ] + }, + "total": { + "type": "integer", + "minimum": 0, + "description": "All workers currently allocated to the endpoint.", + "examples": [ + 3 + ] + } + } + }, + "ListEndpointWorkersResponse": { + "type": "object", + "required": [ + "workers", + "summary" + ], + "properties": { + "workers": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Worker" + } + }, + "summary": { + "$ref": "#/components/schemas/WorkerSummary" + }, + "endpointVersion": { + "type": [ + "integer", + "null" + ], + "description": "The endpoint's current configuration version. A worker whose\n`version` differs is running stale config (see `worker.isStale`).\nNull if unknown.\n", + "examples": [ + 4 + ] + } + } + }, + "ReleaseSource": { + "type": "string", + "description": "What produced the release.\n- `GIT_BUILD` — a completed GitHub build (see `buildId`)\n- `MANUAL` — a manual configuration change\n", + "x-enum-varnames": [ + "ReleaseSourceGitBuild", + "ReleaseSourceManual" + ], + "enum": [ + "GIT_BUILD", + "MANUAL" + ] + }, + "ReleaseDiffEntry": { + "type": "object", + "required": [ + "field", + "old", + "new" + ], + "properties": { + "field": { + "type": "string", + "description": "The changed configuration field. Top-level (e.g. `gpuCount`,\n`locations`) or template-scoped (e.g. `template.imageName`,\n`template.env`).\n", + "examples": [ + "template.imageName" + ] + }, + "old": { + "description": "Previous value, as raw JSON. Null when the field was added." + }, + "new": { + "description": "New value, as raw JSON. Null when the field was removed." + } + } + }, + "Release": { + "type": "object", + "required": [ + "id", + "source", + "createdAt", + "workerCount", + "diff" + ], + "properties": { + "id": { + "type": "string", + "examples": [ + "rel_abc123" + ] + }, + "version": { + "type": [ + "integer", + "null" + ], + "description": "The endpoint configuration version this release produced.", + "examples": [ + 4 + ] + }, + "source": { + "$ref": "#/components/schemas/ReleaseSource" + }, + "buildId": { + "type": [ + "string", + "null" + ], + "description": "The GitHub build that produced this release. Set when `source` is\n`GIT_BUILD`; null for `MANUAL` releases. Fetch build detail/logs via\n`/v2/serverless/{id}/builds/{buildId}`.\n", + "examples": [ + "build_abc123" + ] + }, + "createdByUserId": { + "type": [ + "string", + "null" + ], + "description": "ID of the user who created the release." + }, + "workerCount": { + "type": "integer", + "minimum": 0, + "description": "Workers currently running this release's version.", + "examples": [ + 2 + ] + }, + "createdAt": { + "type": "string", + "format": "date-time", + "examples": [ + "2026-03-13T20:00:00Z" + ] + }, + "diff": { + "type": "array", + "description": "Configuration fields that changed in this release.", + "items": { + "$ref": "#/components/schemas/ReleaseDiffEntry" + } + } + } + }, + "RolloutSummary": { + "type": "object", + "required": [ + "inProgress", + "workersOnLatest", + "workersTotal", + "percentOnLatest" + ], + "properties": { + "inProgress": { + "type": "boolean", + "description": "True while any worker is still running an older version.", + "examples": [ + true + ] + }, + "workersOnLatest": { + "type": "integer", + "minimum": 0, + "description": "Workers running the endpoint's current version.", + "examples": [ + 2 + ] + }, + "workersTotal": { + "type": "integer", + "minimum": 0, + "description": "All workers currently allocated to the endpoint.", + "examples": [ + 3 + ] + }, + "percentOnLatest": { + "type": "integer", + "minimum": 0, + "maximum": 100, + "description": "Percentage of workers on the current version (0 when there are no workers).", + "examples": [ + 67 + ] + } + } + }, + "ListEndpointReleasesResponse": { + "type": "object", + "required": [ + "rollout", + "releases" + ], + "properties": { + "endpointVersion": { + "type": [ + "integer", + "null" + ], + "description": "The endpoint's current configuration version. Null if unknown.", + "examples": [ + 4 + ] + }, + "rollout": { + "$ref": "#/components/schemas/RolloutSummary" + }, + "releases": { + "type": "array", + "description": "Release history, newest first.", + "items": { + "$ref": "#/components/schemas/Release" + } + } + } + }, + "CreateEndpointRequest": { + "allOf": [ + { + "$ref": "#/components/schemas/ContainerConfig" + }, + { + "type": "object", + "required": [ + "name", + "image", + "gpu" + ], + "properties": { + "name": { + "type": "string", + "minLength": 1, + "examples": [ + "my-inference" + ] + }, + "gpu": { + "allOf": [ + { + "$ref": "#/components/schemas/EndpointGpuConfig" + } + ], + "unevaluatedProperties": false + }, + "workers": { + "type": "object", + "additionalProperties": false, + "properties": { + "min": { + "type": "integer", + "minimum": 0, + "default": 0 + }, + "max": { + "type": "integer", + "minimum": 0, + "default": 3 + } + } + }, + "scaling": { + "type": "object", + "additionalProperties": false, + "properties": { + "type": { + "$ref": "#/components/schemas/ScalerType" + }, + "value": { + "type": "number", + "format": "float", + "minimum": 0.5, + "default": 4 + }, + "idleTimeout": { + "type": "integer", + "minimum": 0, + "default": 5 + } + } + }, + "dataCenterIds": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Preferred data centers for placement. Omit or pass an empty array to let the scheduler choose." + }, + "networkVolumes": { + "type": "array", + "items": { + "type": "string" + } + }, + "timeout": { + "type": "integer", + "default": 300000 + }, + "flashboot": { + "allOf": [ + { + "$ref": "#/components/schemas/FlashBoot" + } + ], + "default": "OFF" + } + } + } + ], + "unevaluatedProperties": false + }, + "UpdateEndpointRequest": { + "allOf": [ + { + "$ref": "#/components/schemas/ContainerConfig" + }, + { + "type": "object", + "description": "Only provided fields are changed.", + "properties": { + "name": { + "type": "string", + "minLength": 1 + }, + "gpu": { + "allOf": [ + { + "$ref": "#/components/schemas/EndpointGpuConfig" + } + ], + "unevaluatedProperties": false + }, + "workers": { + "type": "object", + "additionalProperties": false, + "properties": { + "min": { + "type": "integer", + "minimum": 0 + }, + "max": { + "type": "integer", + "minimum": 0 + } + } + }, + "scaling": { + "type": "object", + "additionalProperties": false, + "properties": { + "type": { + "$ref": "#/components/schemas/ScalerType" + }, + "value": { + "type": "number", + "format": "float", + "minimum": 0.5 + }, + "idleTimeout": { + "type": "integer", + "minimum": 0 + } + } + }, + "dataCenterIds": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Preferred data centers for placement. Omit or pass an empty array to let the scheduler choose." + }, + "networkVolumes": { + "type": "array", + "items": { + "type": "string" + } + }, + "timeout": { + "type": "integer" + }, + "flashboot": { + "$ref": "#/components/schemas/FlashBoot" + } + } + } + ], + "unevaluatedProperties": false + }, + "Utilization": { + "type": "object", + "description": "Single-value utilization percentage (0–100). Shared by `cpu` and `memory`.", + "properties": { + "util": { + "type": "integer", + "examples": [ + 45 + ] + } + } + }, + "PodGpuUtilization": { + "type": "object", + "description": "Per-GPU utilization metrics.", + "properties": { + "util": { + "type": "integer", + "examples": [ + 94 + ] + }, + "memoryUtil": { + "type": "integer", + "examples": [ + 78 + ] + } + } + }, + "PodRuntimePort": { + "type": "object", + "description": "Live port mapping for a running pod.", + "properties": { + "private": { + "type": "integer", + "examples": [ + 8888 + ] + }, + "public": { + "type": [ + "integer", + "null" + ], + "examples": [ + 43210 + ] + }, + "type": { + "type": "string", + "examples": [ + "http" + ] + }, + "ip": { + "type": [ + "string", + "null" + ], + "examples": [ + "45.23.12.1" + ] + } + } + }, + "PodRuntime": { + "type": "object", + "description": "Live utilization metrics for a running pod.", + "properties": { + "uptime": { + "type": "integer", + "description": "Seconds since the container started", + "examples": [ + 3600 + ] + }, + "gpus": { + "type": "array", + "items": { + "$ref": "#/components/schemas/PodGpuUtilization" + } + }, + "cpu": { + "$ref": "#/components/schemas/Utilization" + }, + "memory": { + "$ref": "#/components/schemas/Utilization" + }, + "ports": { + "type": "array", + "items": { + "$ref": "#/components/schemas/PodRuntimePort" + } + } + } + }, + "PodStatus": { + "type": "string", + "description": "Lifecycle status of a pod.\n- `PROVISIONING` — pod is being allocated\n- `STARTING` — container is starting\n- `RUNNING` — container is healthy\n- `EXITED` — container exited (stopped)\n- `ERROR` — container is in an unrecoverable error state\n- `TERMINATED` — pod has been permanently deleted\n", + "enum": [ + "PROVISIONING", + "STARTING", + "RUNNING", + "EXITED", + "ERROR", + "TERMINATED" + ] + }, + "PodAction": { + "type": "string", + "description": "State transition to trigger on a pod.", + "enum": [ + "start", + "stop", + "restart", + "terminate" + ] + }, + "LogSource": { + "type": "string", + "description": "Log source to include in a log stream.\n- `container` — container stdout/stderr log stream\n- `system` — host lifecycle/userlogs stream\n", + "x-enum-varnames": [ + "LogSourceContainer", + "LogSourceSystem" + ], + "enum": [ + "container", + "system" + ] + }, + "Cloud": { + "type": "string", + "description": "Cloud tier.\n- `SECURE` — Runpod-owned datacenter hardware\n- `COMMUNITY` — community-hosted hardware\n", + "enum": [ + "SECURE", + "COMMUNITY" + ] + }, + "TemplateCategory": { + "type": "string", + "description": "Controls how the template is grouped and filtered in the Runpod console.\nIt does not affect hardware selection, scheduling, or billing.\n- `CPU` — CPU-only workloads\n- `NVIDIA` — NVIDIA GPU workloads\n- `AMD` — AMD GPU workloads\n", + "enum": [ + "CPU", + "NVIDIA", + "AMD" + ] + }, + "PodGlobalNetworking": { + "type": "object", + "required": [ + "enabled" + ], + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether global networking is enabled, giving the pod a private IP reachable across data centers. Derived from whether the pod has an assigned global-network address.", + "examples": [ + true + ] + }, + "ip": { + "type": "string", + "description": "The pod's assigned global-networking IP. Present only when enabled.", + "examples": [ + "10.65.1.42" + ] + }, + "internalDns": { + "type": "string", + "description": "Internal DNS name (`.runpod.internal`), reachable from other globally-networked pods in the same account. Present only when enabled.", + "examples": [ + "gfj8b292vyg08g.runpod.internal" + ] + } + } + }, + "Pod": { + "allOf": [ + { + "$ref": "#/components/schemas/ContainerConfig" + }, + { + "type": "object", + "required": [ + "id", + "name", + "status", + "actions", + "image", + "args", + "disk", + "mounts", + "ports", + "env", + "registry", + "cloud", + "dataCenterId", + "template", + "cost", + "locked", + "runtime", + "createdAt", + "startedAt", + "globalNetworking" + ], + "properties": { + "id": { + "type": "string", + "examples": [ + "pod_abc123" + ] + }, + "name": { + "type": "string", + "examples": [ + "my-training-pod" + ] + }, + "status": { + "$ref": "#/components/schemas/PodStatus" + }, + "actions": { + "type": "array", + "description": "Valid state transitions for the current status.", + "items": { + "$ref": "#/components/schemas/PodAction" + } + }, + "mounts": { + "$ref": "#/components/schemas/Mounts" + }, + "gpu": { + "description": "Present for GPU pods; omitted from CPU pods.", + "allOf": [ + { + "$ref": "#/components/schemas/GpuConfig" + } + ] + }, + "cpu": { + "description": "Present for CPU pods; omitted from GPU pods.", + "allOf": [ + { + "$ref": "#/components/schemas/CpuConfig" + } + ] + }, + "cloud": { + "$ref": "#/components/schemas/Cloud" + }, + "dataCenterId": { + "type": [ + "string", + "null" + ], + "description": "Data center where the pod is running (assigned by scheduler)", + "examples": [ + "US-TX-3" + ] + }, + "template": { + "type": [ + "string", + "null" + ], + "description": "ID of the template this pod was created from", + "examples": [ + null + ] + }, + "cost": { + "type": "number", + "format": "float", + "description": "Current cost in USD per hour (0.0 when EXITED or TERMINATED)", + "examples": [ + 0.35 + ] + }, + "locked": { + "type": "boolean", + "description": "Whether the pod is locked (prevents stopping or resetting)", + "examples": [ + false + ] + }, + "globalNetworking": { + "$ref": "#/components/schemas/PodGlobalNetworking" + }, + "runtime": { + "description": "Live utilization metrics. Null when the pod is not RUNNING.", + "anyOf": [ + { + "$ref": "#/components/schemas/PodRuntime" + }, + { + "type": "null" + } + ] + }, + "createdAt": { + "type": "string", + "format": "date-time", + "examples": [ + "2026-03-13T20:00:00Z" + ] + }, + "startedAt": { + "type": [ + "string", + "null" + ], + "format": "date-time", + "examples": [ + "2026-03-13T20:00:00Z" + ] + } + } + } + ] + }, + "CreatePodRequest": { + "allOf": [ + { + "$ref": "#/components/schemas/ContainerConfig" + }, + { + "type": "object", + "required": [ + "name", + "image" + ], + "description": "Request body for creating a pod. Exactly one of `gpu` or `cpu`\nmust be set — enforced at the handler layer. For CPU pods, memory\nis derived by the API from the selected flavor's RAM multiplier;\nclients provide only CPU flavor and vCPU count. CPU pods support\ncontainer disk and network volumes only; `mounts.persistent` is\ninvalid when `cpu` is set.\n", + "properties": { + "name": { + "type": "string", + "minLength": 1, + "examples": [ + "my-training-pod" + ] + }, + "mounts": { + "$ref": "#/components/schemas/Mounts" + }, + "gpu": { + "allOf": [ + { + "$ref": "#/components/schemas/GpuConfig" + } + ], + "unevaluatedProperties": false + }, + "cpu": { + "$ref": "#/components/schemas/CreateCpuConfig" + }, + "cloud": { + "allOf": [ + { + "$ref": "#/components/schemas/Cloud" + } + ], + "default": "SECURE", + "description": "Cloud tier. Defaults to `SECURE` when omitted." + }, + "dataCenterIds": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Preferred data centers for placement. Omit or pass an empty\narray to let the scheduler choose.\n", + "examples": [ + [ + "US-TX-3" + ] + ] + }, + "globalNetworking": { + "type": "boolean", + "default": false, + "description": "Enable global networking, giving the pod a private IP reachable across data centers. Requires an NVIDIA GPU and a global-networking-enabled data center (both enforced upstream). See `GET /v2/catalog/datacenters` (`globalNetwork`) for eligible data centers.", + "examples": [ + false + ] + } + } + } + ], + "unevaluatedProperties": false + }, + "UpdatePodRequest": { + "allOf": [ + { + "$ref": "#/components/schemas/ContainerConfig" + }, + { + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 1 + }, + "mounts": { + "$ref": "#/components/schemas/Mounts" + }, + "locked": { + "type": "boolean", + "description": "Lock the pod (true) or unlock it (false). Locked pods cannot be stopped or reset." + }, + "globalNetworking": { + "type": "boolean", + "description": "Enable (true) or disable (false) global networking. Takes effect on the next pod start/restart, not live. Requires an NVIDIA GPU and a global-networking-enabled data center (both enforced upstream). See `GET /v2/catalog/datacenters` (`globalNetwork`) for eligible data centers." + } + } + } + ], + "unevaluatedProperties": false + }, + "PodActionRequest": { + "type": "object", + "additionalProperties": false, + "required": [ + "action" + ], + "properties": { + "action": { + "$ref": "#/components/schemas/PodAction" + } + } + }, + "ListPodsResponse": { + "type": "object", + "required": [ + "pods" + ], + "properties": { + "pods": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Pod" + } + } + } + }, + "Template": { + "allOf": [ + { + "$ref": "#/components/schemas/ContainerConfig" + }, + { + "type": "object", + "required": [ + "id", + "name", + "image", + "args", + "disk", + "mounts", + "ports", + "env", + "registry", + "serverless", + "public", + "category" + ], + "properties": { + "id": { + "type": "string", + "examples": [ + "tpl_abc" + ] + }, + "name": { + "type": "string", + "examples": [ + "My PyTorch Template" + ] + }, + "mounts": { + "$ref": "#/components/schemas/TemplateMounts" + }, + "serverless": { + "type": "boolean", + "description": "Whether this template is for serverless workers (true) or pods (false)", + "examples": [ + false + ] + }, + "public": { + "type": "boolean", + "description": "Whether this template is visible to other Runpod users", + "examples": [ + false + ] + }, + "category": { + "$ref": "#/components/schemas/TemplateCategory" + } + } + } + ] + }, + "CreateTemplateRequest": { + "allOf": [ + { + "$ref": "#/components/schemas/ContainerConfig" + }, + { + "type": "object", + "required": [ + "name", + "image" + ], + "properties": { + "name": { + "type": "string", + "minLength": 1, + "examples": [ + "My PyTorch Template" + ] + }, + "mounts": { + "$ref": "#/components/schemas/TemplateMounts" + }, + "serverless": { + "type": "boolean", + "default": false + }, + "public": { + "type": "boolean", + "default": false + }, + "category": { + "description": "Optional. Defaults to `NVIDIA` when omitted.", + "allOf": [ + { + "$ref": "#/components/schemas/TemplateCategory" + } + ], + "default": "NVIDIA" + } + } + } + ], + "unevaluatedProperties": false + }, + "UpdateTemplateRequest": { + "allOf": [ + { + "$ref": "#/components/schemas/ContainerConfig" + }, + { + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 1 + }, + "mounts": { + "$ref": "#/components/schemas/TemplateMounts" + }, + "serverless": { + "type": "boolean" + }, + "public": { + "type": "boolean" + }, + "category": { + "$ref": "#/components/schemas/TemplateCategory" + } + } + } + ], + "unevaluatedProperties": false + }, + "ListTemplatesResponse": { + "type": "object", + "required": [ + "templates" + ], + "properties": { + "templates": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Template" + } + } + } + }, + "NetworkVolume": { + "type": "object", + "required": [ + "id", + "name", + "size", + "dataCenter", + "type" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique network volume identifier", + "examples": [ + "agv6w2qcg7" + ] + }, + "name": { + "type": "string", + "description": "Human-readable name (not required to be unique)", + "examples": [ + "my-dataset" + ] + }, + "size": { + "type": "integer", + "minimum": 10, + "maximum": 4096, + "description": "Allocated storage in GB", + "examples": [ + 50 + ] + }, + "dataCenter": { + "type": "string", + "description": "Data center location; immutable after creation", + "examples": [ + "EU-RO-1" + ] + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/VolumeType" + } + ], + "description": "Storage tier of this volume. Set at creation and immutable." + } + } + }, + "CreateNetworkVolumeRequest": { + "type": "object", + "additionalProperties": false, + "required": [ + "name", + "size", + "dataCenter" + ], + "properties": { + "name": { + "type": "string", + "minLength": 1, + "description": "Human-readable name", + "examples": [ + "my-dataset" + ] + }, + "size": { + "type": "integer", + "minimum": 10, + "maximum": 4096, + "description": "Storage to allocate in GB", + "examples": [ + 50 + ] + }, + "dataCenter": { + "type": "string", + "minLength": 1, + "description": "Data center in which to create the volume", + "examples": [ + "EU-RO-1" + ] + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/VolumeType" + } + ], + "description": "Storage tier for the volume. Optional. When omitted, the volume is\nprovisioned using the requested data center's default (primary)\nstorage tier. HIGH_PERFORMANCE provisions a high-performance (HPS)\nvolume; STANDARD provisions a standard volume. A volume's tier is\nimmutable after creation.\n" + } + } + }, + "UpdateNetworkVolumeRequest": { + "type": "object", + "additionalProperties": false, + "minProperties": 1, + "description": "Only the provided fields are updated. At least one field must be\npresent; an empty body is rejected.\n", + "properties": { + "name": { + "type": "string", + "minLength": 1, + "description": "New human-readable name", + "examples": [ + "renamed-volume" + ] + }, + "size": { + "type": "integer", + "minimum": 10, + "maximum": 4096, + "description": "New size in GB. Must be greater than or equal to the current size —\nnetwork volume storage cannot be reduced.\n", + "examples": [ + 100 + ] + } + } + }, + "ListNetworkVolumesResponse": { + "type": "object", + "required": [ + "networkVolumes" + ], + "properties": { + "networkVolumes": { + "type": "array", + "items": { + "$ref": "#/components/schemas/NetworkVolume" + } + } + } + }, + "Registry": { + "type": "object", + "required": [ + "id", + "name" + ], + "properties": { + "id": { + "type": "string", + "examples": [ + "reg_abc" + ] + }, + "name": { + "type": "string", + "examples": [ + "my-private-registry" + ] + } + } + }, + "CreateRegistryRequest": { + "type": "object", + "additionalProperties": false, + "required": [ + "name", + "username", + "password" + ], + "properties": { + "name": { + "type": "string", + "minLength": 1, + "examples": [ + "my-private-registry" + ] + }, + "username": { + "type": "string", + "minLength": 1, + "description": "Registry username (write-only, not returned in responses)" + }, + "password": { + "type": "string", + "minLength": 1, + "description": "Registry password (write-only, not returned in responses)" + } + } + }, + "ListRegistriesResponse": { + "type": "object", + "required": [ + "registries" + ], + "properties": { + "registries": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Registry" + } + } + } + }, + "EcrDelegation": { + "type": "object", + "required": [ + "id", + "delegatorUserId", + "awsUser", + "repository", + "tag", + "awsRegion", + "createdAt" + ], + "properties": { + "id": { + "type": "string", + "description": "Delegation identifier", + "examples": [ + "deleg_abc123" + ] + }, + "name": { + "type": [ + "string", + "null" + ], + "description": "Optional name for the delegation", + "examples": [ + "my-delegation" + ] + }, + "delegatorUserId": { + "type": "string", + "description": "User ID that created the delegation", + "examples": [ + "user_xyz" + ] + }, + "awsUser": { + "type": "string", + "description": "AWS user/role being delegated", + "examples": [ + "123456789" + ] + }, + "repository": { + "type": "string", + "description": "ECR repository name", + "examples": [ + "runpod/deployment" + ] + }, + "tag": { + "type": "string", + "description": "ECR image tag", + "examples": [ + "latest" + ] + }, + "awsRegion": { + "type": "string", + "description": "AWS region", + "examples": [ + "us-east-2" + ] + }, + "dockerRegistryUri": { + "type": "string", + "description": "Formatted ECR registry URI for Docker login", + "examples": [ + "123456789.dkr.ecr.us-east-2.amazonaws.com" + ] + }, + "createdAt": { + "type": "string", + "format": "date-time", + "description": "When the delegation was created", + "examples": [ + "2026-03-13T20:00:00Z" + ] + } + } + }, + "CreateDelegationRequest": { + "type": "object", + "additionalProperties": false, + "required": [ + "resource" + ], + "properties": { + "resource": { + "type": "string", + "description": "ECR resource ARN", + "examples": [ + "arn:aws:ecr:us-east-2:418399314813:repository/runpod/deployment" + ] + }, + "name": { + "type": [ + "string", + "null" + ], + "description": "Optional name for the delegation", + "examples": [ + "my-delegation" + ] + } + } + }, + "ListDelegationsResponse": { + "type": "object", + "required": [ + "delegations" + ], + "properties": { + "delegations": { + "type": "array", + "items": { + "$ref": "#/components/schemas/EcrDelegation" + } + } + } + }, + "GpuManufacturer": { + "type": "string", + "description": "Canonical GPU hardware manufacturer.", + "x-enum-varnames": [ + "GpuManufacturerNVIDIA", + "GpuManufacturerAMD", + "GpuManufacturerUNKNOWN" + ], + "enum": [ + "NVIDIA", + "AMD", + "UNKNOWN" + ] + }, + "GpuType": { + "type": "object", + "required": [ + "id", + "name", + "pool", + "manufacturer", + "memory", + "secure", + "community", + "price", + "maxCount" + ], + "properties": { + "id": { + "type": "string", + "description": "Individual GPU type identifier (use for pod creation)", + "examples": [ + "NVIDIA GeForce RTX 4090" + ] + }, + "name": { + "type": "string", + "examples": [ + "RTX 4090" + ] + }, + "pool": { + "type": [ + "string", + "null" + ], + "description": "Serverless GPU pool ID (use for serverless endpoint creation). Null if GPU is not in a serverless pool.", + "examples": [ + "ADA_24" + ] + }, + "manufacturer": { + "$ref": "#/components/schemas/GpuManufacturer" + }, + "memory": { + "type": "integer", + "description": "VRAM in GB", + "examples": [ + 24 + ] + }, + "secure": { + "type": "boolean", + "description": "Available on secure cloud", + "examples": [ + true + ] + }, + "community": { + "type": "boolean", + "description": "Available on community cloud", + "examples": [ + true + ] + }, + "price": { + "type": "object", + "required": [ + "secure", + "community" + ], + "properties": { + "secure": { + "type": "number", + "format": "float", + "examples": [ + 0.44 + ] + }, + "community": { + "type": "number", + "format": "float", + "examples": [ + 0.31 + ] + } + } + }, + "maxCount": { + "type": "object", + "required": [ + "secure", + "community" + ], + "properties": { + "secure": { + "type": "integer", + "examples": [ + 8 + ] + }, + "community": { + "type": "integer", + "examples": [ + 4 + ] + } + } + }, + "availability": { + "description": "Overall GPU availability. Present only when requested with include=AVAILABILITY.", + "$ref": "#/components/schemas/AvailabilityLevel" + }, + "dataCenters": { + "type": "array", + "description": "Per-datacenter GPU availability. Present only when requested with include=AVAILABILITY.", + "items": { + "$ref": "#/components/schemas/DataCenterAvailability" + } + } + } + }, + "AvailabilityLevel": { + "type": "string", + "description": "Catalog stock availability level.", + "enum": [ + "NONE", + "LOW", + "MEDIUM", + "HIGH" + ] + }, + "Product": { + "type": "string", + "description": "Catalog product availability context.", + "enum": [ + "POD", + "CLUSTER", + "SERVERLESS" + ] + }, + "CpuProduct": { + "type": "string", + "description": "CPU catalog product availability context.", + "enum": [ + "POD", + "SERVERLESS" + ] + }, + "CatalogInclude": { + "type": "string", + "description": "Catalog include expansion. Only AVAILABILITY is supported today; additional include values may be added in the future.", + "enum": [ + "AVAILABILITY" + ] + }, + "DataCenterInclude": { + "type": "string", + "description": "Data center catalog availability expansion.", + "enum": [ + "GPU_AVAILABILITY", + "CPU_AVAILABILITY" + ] + }, + "GpuCloudFilter": { + "type": "string", + "description": "GPU availability cloud filter.", + "enum": [ + "SECURE", + "COMMUNITY" + ] + }, + "VolumeType": { + "type": "string", + "description": "Data center network volume storage type.", + "enum": [ + "STANDARD", + "HIGH_PERFORMANCE" + ] + }, + "CatalogResourceAvailability": { + "type": "object", + "required": [ + "id", + "name", + "availability" + ], + "properties": { + "id": { + "type": "string", + "description": "Catalog resource identifier.", + "examples": [ + "NVIDIA GeForce RTX 4090" + ] + }, + "name": { + "type": "string", + "description": "Human-readable catalog resource name.", + "examples": [ + "RTX 4090" + ] + }, + "availability": { + "$ref": "#/components/schemas/AvailabilityLevel" + } + } + }, + "DataCenterAvailability": { + "type": "object", + "required": [ + "id", + "name", + "availability" + ], + "properties": { + "id": { + "type": "string", + "description": "Data center identifier.", + "examples": [ + "US-CA-2" + ] + }, + "name": { + "type": "string", + "description": "Human-readable data center name.", + "examples": [ + "US California 2" + ] + }, + "availability": { + "$ref": "#/components/schemas/AvailabilityLevel" + } + } + }, + "ListGpuTypesResponse": { + "type": "object", + "required": [ + "gpus" + ], + "properties": { + "gpus": { + "type": "array", + "items": { + "$ref": "#/components/schemas/GpuType" + } + } + } + }, + "CpuType": { + "type": "object", + "required": [ + "id", + "name", + "group", + "vcpu", + "ramGbPerVcpu", + "price" + ], + "properties": { + "id": { + "type": "string", + "description": "CPU flavor identifier (use in cpu.id for pod creation)", + "examples": [ + "cpu5c" + ] + }, + "name": { + "type": "string", + "description": "Human-readable flavor name", + "examples": [ + "Compute-Optimized" + ] + }, + "group": { + "type": "string", + "description": "CPU generation group", + "examples": [ + "Gen 5" + ] + }, + "vcpu": { + "type": "object", + "required": [ + "min", + "max" + ], + "properties": { + "min": { + "type": "integer", + "examples": [ + 2 + ] + }, + "max": { + "type": "integer", + "examples": [ + 32 + ] + } + } + }, + "ramGbPerVcpu": { + "type": "number", + "format": "float", + "description": "GB of RAM allocated per vCPU. Multiply by the chosen vCPU\ncount (within `vcpu.min`..`vcpu.max`) to get the total RAM\nfor an instance of this flavor. May be fractional.\n", + "examples": [ + 2.5 + ] + }, + "price": { + "type": "object", + "required": [ + "securePerVcpu", + "serverlessPerVcpu" + ], + "properties": { + "securePerVcpu": { + "type": "number", + "format": "float", + "description": "Price for secure pods per vCPU. Multiply by the chosen vCPU\ncount (within `vcpu.min`..`vcpu.max`) to get the total price.\n", + "examples": [ + 0.04 + ] + }, + "serverlessPerVcpu": { + "type": "number", + "format": "float", + "description": "Price for serverless per vCPU. Multiply by the chosen vCPU\ncount (within `vcpu.min`..`vcpu.max`) to get the total price.\n", + "examples": [ + 0.03 + ] + } + } + }, + "availability": { + "description": "Overall CPU availability. Present only when requested with include=AVAILABILITY.", + "$ref": "#/components/schemas/AvailabilityLevel" + }, + "dataCenters": { + "type": "array", + "description": "Per-datacenter CPU availability. Present only when requested with include=AVAILABILITY.", + "items": { + "$ref": "#/components/schemas/DataCenterAvailability" + } + } + } + }, + "ListCpuTypesResponse": { + "type": "object", + "required": [ + "cpus" + ], + "properties": { + "cpus": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CpuType" + } + } + } + }, + "DataCenter": { + "type": "object", + "required": [ + "id", + "name", + "region", + "networkVolumeTypes", + "compliance", + "globalNetwork" + ], + "properties": { + "id": { + "type": "string", + "examples": [ + "US-TX-3" + ] + }, + "name": { + "type": "string", + "examples": [ + "US Texas 3" + ] + }, + "region": { + "$ref": "#/components/schemas/DataCenterRegion" + }, + "globalNetwork": { + "type": "boolean", + "description": "Whether this data center supports global networking (private cross-datacenter pod-to-pod network).", + "examples": [ + true + ] + }, + "networkVolumeTypes": { + "type": "array", + "items": { + "$ref": "#/components/schemas/VolumeType" + }, + "description": "Network volume tiers this DC supports. Empty = none." + }, + "compliance": { + "type": "array", + "description": "Compliance certifications held by this data center", + "items": { + "$ref": "#/components/schemas/Compliance" + }, + "examples": [ + [ + "GDPR", + "ISO_IEC_27001", + "SOC_2_TYPE_2" + ] + ] + }, + "gpuAvailability": { + "type": "array", + "description": "Per-GPU availability in this data center. Present only when requested with include=GPU_AVAILABILITY.", + "items": { + "$ref": "#/components/schemas/CatalogResourceAvailability" + } + }, + "cpuAvailability": { + "type": "array", + "description": "Per-CPU availability in this data center. Present only when requested with include=CPU_AVAILABILITY.", + "items": { + "$ref": "#/components/schemas/CatalogResourceAvailability" + } + } + } + }, + "DataCenterRegion": { + "type": "string", + "description": "Continental region containing the data center.", + "examples": [ + "EUROPE" + ], + "enum": [ + "NORTH_AMERICA", + "SOUTH_AMERICA", + "EUROPE", + "ASIA", + "MIDDLE_EAST", + "AFRICA", + "OCEANIA", + "ANTARCTICA", + "UNKNOWN" + ] + }, + "Compliance": { + "type": "string", + "description": "Compliance certifications.", + "enum": [ + "GDPR", + "ISO_IEC_27001", + "ISO_14001", + "PCI_DSS", + "HITRUST", + "SOC_1_TYPE_2", + "SOC_2_TYPE_2", + "SOC_3_TYPE_2", + "ITAR", + "FISMA_HIGH", + "HIPAA", + "RENEWABLE" + ] + }, + "ListDataCentersResponse": { + "type": "object", + "required": [ + "dataCenters" + ], + "properties": { + "dataCenters": { + "type": "array", + "items": { + "$ref": "#/components/schemas/DataCenter" + } + } + } + }, + "BillingTimeRange": { + "type": "object", + "description": "Half-open time range [startTime, endTime) in RFC 3339. On a record it is the time bucket; on a query echo it is the resolved window.\n", + "required": [ + "startTime", + "endTime" + ], + "properties": { + "startTime": { + "type": "string", + "format": "date-time", + "description": "Start of the range, inclusive (RFC 3339).", + "examples": [ + "2026-06-01T00:00:00Z" + ] + }, + "endTime": { + "type": "string", + "format": "date-time", + "description": "End of the range, exclusive (RFC 3339).", + "examples": [ + "2026-06-02T00:00:00Z" + ] + } + } + }, + "BillingBucketSize": { + "type": "string", + "enum": [ + "hour", + "day", + "week", + "month", + "year" + ], + "x-enum-varnames": [ + "BillingBucketSizeHour", + "BillingBucketSizeDay", + "BillingBucketSizeWeek", + "BillingBucketSizeMonth", + "BillingBucketSizeYear" + ], + "default": "day", + "description": "Length of each billing time bucket.", + "examples": [ + "day" + ] + }, + "BillingAmounts": { + "type": "object", + "description": "Total spend across all billable Runpod resources with each cost component broken out, fully prefixed by resource. Backs the aggregate record's amounts and the metadata totals.\n", + "required": [ + "totalAmount", + "podGpuAmount", + "podCpuAmount", + "podDiskAmount", + "serverlessGpuAmount", + "serverlessCpuAmount", + "serverlessDiskAmount", + "serverlessFeeAmount", + "storageStandardAmount", + "storageHighPerformanceAmount", + "endpointAmount", + "clusterGpuAmount", + "clusterDiskAmount", + "clusterNetworkingAmount" + ], + "properties": { + "totalAmount": { + "type": "number", + "format": "double", + "description": "Total cost in USD for the bucket across all resources.", + "examples": [ + 42.34 + ] + }, + "podGpuAmount": { + "type": "number", + "format": "double", + "description": "GPU pod compute cost in USD for the bucket." + }, + "podCpuAmount": { + "type": "number", + "format": "double", + "description": "CPU pod compute cost in USD for the bucket." + }, + "podDiskAmount": { + "type": "number", + "format": "double", + "description": "Pod disk cost in USD for the bucket." + }, + "serverlessGpuAmount": { + "type": "number", + "format": "double", + "description": "Serverless GPU compute cost in USD for the bucket." + }, + "serverlessCpuAmount": { + "type": "number", + "format": "double", + "description": "Serverless CPU compute cost in USD for the bucket." + }, + "serverlessDiskAmount": { + "type": "number", + "format": "double", + "description": "Serverless disk cost in USD for the bucket." + }, + "serverlessFeeAmount": { + "type": "number", + "format": "double", + "description": "Serverless platform fee in USD for the bucket." + }, + "storageStandardAmount": { + "type": "number", + "format": "double", + "description": "Standard network volume storage cost in USD for the bucket." + }, + "storageHighPerformanceAmount": { + "type": "number", + "format": "double", + "description": "High-performance network volume storage cost in USD for the bucket." + }, + "endpointAmount": { + "type": "number", + "format": "double", + "description": "Runpod public endpoint cost in USD for the bucket." + }, + "clusterGpuAmount": { + "type": "number", + "format": "double", + "description": "Instant Cluster GPU compute cost in USD for the bucket." + }, + "clusterDiskAmount": { + "type": "number", + "format": "double", + "description": "Instant Cluster disk cost in USD for the bucket." + }, + "clusterNetworkingAmount": { + "type": "number", + "format": "double", + "description": "Instant Cluster inter-node networking cost in USD for the bucket." + } + } + }, + "BillingRecord": { + "description": "A single time-bucketed record of total spend across all billable Runpod resources, with each cost component broken out. Returned by GET /v2/billing.\n", + "allOf": [ + { + "$ref": "#/components/schemas/BillingTimeRange" + }, + { + "$ref": "#/components/schemas/BillingAmounts" + } + ] + }, + "PodBillingAmounts": { + "type": "object", + "description": "Pod cost components covering both GPU and CPU pods. Backs a record's amounts and the metadata totals.\n", + "required": [ + "totalAmount", + "gpuAmount", + "cpuAmount", + "diskAmount" + ], + "properties": { + "totalAmount": { + "type": "number", + "format": "double", + "description": "Total pod cost in USD for the bucket.", + "examples": [ + 12.34 + ] + }, + "gpuAmount": { + "type": "number", + "format": "double", + "description": "GPU pod compute cost in USD for the bucket." + }, + "cpuAmount": { + "type": "number", + "format": "double", + "description": "CPU pod compute cost in USD for the bucket." + }, + "diskAmount": { + "type": "number", + "format": "double", + "description": "Pod disk cost in USD for the bucket." + } + } + }, + "PodBillingRecord": { + "description": "A single time-bucketed pod billing record, covering both GPU and CPU pods. Returned by GET /v2/billing/pods.\n", + "allOf": [ + { + "$ref": "#/components/schemas/BillingTimeRange" + }, + { + "$ref": "#/components/schemas/PodBillingAmounts" + }, + { + "type": "object", + "required": [ + "podId" + ], + "properties": { + "podId": { + "type": "string", + "description": "The pod this record bills. When the podId filter is set every record carries that id; otherwise one record is emitted per pod per bucket.\n", + "examples": [ + "pod_abc123" + ] + } + } + } + ] + }, + "ServerlessBillingAmounts": { + "type": "object", + "description": "Serverless cost components. Backs a record's amounts and the metadata totals.\n", + "required": [ + "totalAmount", + "gpuAmount", + "cpuAmount", + "diskAmount", + "feeAmount" + ], + "properties": { + "totalAmount": { + "type": "number", + "format": "double", + "description": "Total serverless cost in USD for the bucket.", + "examples": [ + 8.9 + ] + }, + "gpuAmount": { + "type": "number", + "format": "double", + "description": "Serverless GPU compute cost in USD for the bucket." + }, + "cpuAmount": { + "type": "number", + "format": "double", + "description": "Serverless CPU compute cost in USD for the bucket." + }, + "diskAmount": { + "type": "number", + "format": "double", + "description": "Serverless disk cost in USD for the bucket." + }, + "feeAmount": { + "type": "number", + "format": "double", + "description": "Serverless platform fee in USD for the bucket." + } + } + }, + "ServerlessBillingRecord": { + "description": "A single time-bucketed serverless billing record. Returned by GET /v2/billing/serverless.\n", + "allOf": [ + { + "$ref": "#/components/schemas/BillingTimeRange" + }, + { + "$ref": "#/components/schemas/ServerlessBillingAmounts" + }, + { + "type": "object", + "required": [ + "serverlessId" + ], + "properties": { + "serverlessId": { + "type": "string", + "description": "The serverless endpoint this record bills. When the serverlessId filter is set every record carries that id; otherwise one record is emitted per serverless endpoint per bucket.\n", + "examples": [ + "ep_abc123" + ] + } + } + } + ] + }, + "EndpointBillingAmounts": { + "type": "object", + "description": "Runpod public endpoint cost. Backs a record's amounts and the metadata totals.\n", + "required": [ + "totalAmount" + ], + "properties": { + "totalAmount": { + "type": "number", + "format": "double", + "description": "Total public endpoint cost in USD for the bucket.", + "examples": [ + 3.21 + ] + } + } + }, + "EndpointBillingRecord": { + "description": "A single time-bucketed Runpod public endpoint billing record. Returned by GET /v2/billing/endpoints.\n", + "allOf": [ + { + "$ref": "#/components/schemas/BillingTimeRange" + }, + { + "$ref": "#/components/schemas/EndpointBillingAmounts" + } + ] + }, + "NetworkVolumeBillingAmounts": { + "type": "object", + "description": "Network volume storage cost, split into standard and high-performance. Backs a record's amounts and the metadata totals.\n", + "required": [ + "totalAmount", + "standardAmount", + "highPerformanceAmount" + ], + "properties": { + "totalAmount": { + "type": "number", + "format": "double", + "description": "Total network volume cost in USD for the bucket, across standard and high-performance storage.\n", + "examples": [ + 5.79 + ] + }, + "standardAmount": { + "type": "number", + "format": "double", + "description": "Standard storage cost in USD for the bucket." + }, + "highPerformanceAmount": { + "type": "number", + "format": "double", + "description": "High-performance storage cost in USD for the bucket." + } + } + }, + "NetworkVolumeBillingRecord": { + "description": "A single time-bucketed network volume billing record, split into standard and high-performance storage. Returned by GET /v2/billing/networkvolumes.\n", + "allOf": [ + { + "$ref": "#/components/schemas/BillingTimeRange" + }, + { + "$ref": "#/components/schemas/NetworkVolumeBillingAmounts" + }, + { + "type": "object", + "required": [ + "networkVolumeId" + ], + "properties": { + "networkVolumeId": { + "type": "string", + "description": "The network volume this record bills. When the networkVolumeId filter is set every record carries that id; otherwise one record is emitted per network volume per bucket.\n", + "examples": [ + "vol_abc123" + ] + } + } + } + ] + }, + "ClusterBillingAmounts": { + "type": "object", + "description": "Instant Cluster cost components (GPU-only, no CPU). Backs a record's amounts and the metadata totals.\n", + "required": [ + "totalAmount", + "gpuAmount", + "diskAmount", + "networkingAmount" + ], + "properties": { + "totalAmount": { + "type": "number", + "format": "double", + "description": "Total Instant Cluster cost in USD for the bucket.", + "examples": [ + 99 + ] + }, + "gpuAmount": { + "type": "number", + "format": "double", + "description": "Cluster GPU compute cost in USD for the bucket." + }, + "diskAmount": { + "type": "number", + "format": "double", + "description": "Cluster disk cost in USD for the bucket." + }, + "networkingAmount": { + "type": "number", + "format": "double", + "description": "Cluster inter-node networking cost in USD for the bucket." + } + } + }, + "ClusterBillingRecord": { + "description": "A single time-bucketed Instant Cluster billing record. Clusters are GPU-only (no CPU component). Returned by GET /v2/billing/clusters.\n", + "allOf": [ + { + "$ref": "#/components/schemas/BillingTimeRange" + }, + { + "$ref": "#/components/schemas/ClusterBillingAmounts" + }, + { + "type": "object", + "required": [ + "clusterId" + ], + "properties": { + "clusterId": { + "type": "string", + "description": "The Instant Cluster this record bills. When the clusterId filter is set every record carries that id; otherwise one record is emitted per cluster per bucket.\n", + "examples": [ + "cluster_abc123" + ] + } + } + } + ] + }, + "BillingQuery": { + "description": "Resolved query window and granularity (routes without a filter).", + "allOf": [ + { + "$ref": "#/components/schemas/BillingTimeRange" + }, + { + "type": "object", + "required": [ + "bucketSize" + ], + "properties": { + "bucketSize": { + "$ref": "#/components/schemas/BillingBucketSize" + } + } + } + ] + }, + "PodBillingQuery": { + "allOf": [ + { + "$ref": "#/components/schemas/BillingQuery" + }, + { + "type": "object", + "properties": { + "podId": { + "type": [ + "string", + "null" + ], + "description": "The podId filter applied, if any." + } + } + } + ] + }, + "ServerlessBillingQuery": { + "allOf": [ + { + "$ref": "#/components/schemas/BillingQuery" + }, + { + "type": "object", + "properties": { + "serverlessId": { + "type": [ + "string", + "null" + ], + "description": "The serverlessId filter applied, if any." + } + } + } + ] + }, + "NetworkVolumeBillingQuery": { + "allOf": [ + { + "$ref": "#/components/schemas/BillingQuery" + }, + { + "type": "object", + "properties": { + "networkVolumeId": { + "type": [ + "string", + "null" + ], + "description": "The networkVolumeId filter applied, if any." + } + } + } + ] + }, + "ClusterBillingQuery": { + "allOf": [ + { + "$ref": "#/components/schemas/BillingQuery" + }, + { + "type": "object", + "properties": { + "clusterId": { + "type": [ + "string", + "null" + ], + "description": "The clusterId filter applied, if any." + } + } + } + ] + }, + "BillingMetadata": { + "type": "object", + "required": [ + "query", + "recordCount", + "totals" + ], + "properties": { + "query": { + "$ref": "#/components/schemas/BillingQuery" + }, + "recordCount": { + "type": "integer", + "description": "Number of records returned." + }, + "totals": { + "$ref": "#/components/schemas/BillingAmounts" + } + } + }, + "PodBillingMetadata": { + "type": "object", + "required": [ + "query", + "recordCount", + "uniquePodCount", + "totals" + ], + "properties": { + "query": { + "$ref": "#/components/schemas/PodBillingQuery" + }, + "recordCount": { + "type": "integer", + "description": "Number of records returned (buckets times distinct pods)." + }, + "uniquePodCount": { + "type": "integer", + "description": "Number of distinct pods the records span." + }, + "totals": { + "$ref": "#/components/schemas/PodBillingAmounts" + } + } + }, + "ServerlessBillingMetadata": { + "type": "object", + "required": [ + "query", + "recordCount", + "uniqueServerlessCount", + "totals" + ], + "properties": { + "query": { + "$ref": "#/components/schemas/ServerlessBillingQuery" + }, + "recordCount": { + "type": "integer", + "description": "Number of records returned (buckets times distinct endpoints)." + }, + "uniqueServerlessCount": { + "type": "integer", + "description": "Number of distinct serverless endpoints the records span." + }, + "totals": { + "$ref": "#/components/schemas/ServerlessBillingAmounts" + } + } + }, + "EndpointBillingMetadata": { + "type": "object", + "required": [ + "query", + "recordCount", + "totals" + ], + "properties": { + "query": { + "$ref": "#/components/schemas/BillingQuery" + }, + "recordCount": { + "type": "integer" + }, + "totals": { + "$ref": "#/components/schemas/EndpointBillingAmounts" + } + } + }, + "NetworkVolumeBillingMetadata": { + "type": "object", + "required": [ + "query", + "recordCount", + "uniqueNetworkVolumeCount", + "totals" + ], + "properties": { + "query": { + "$ref": "#/components/schemas/NetworkVolumeBillingQuery" + }, + "recordCount": { + "type": "integer", + "description": "Number of records returned (buckets times distinct volumes)." + }, + "uniqueNetworkVolumeCount": { + "type": "integer", + "description": "Number of distinct network volumes the records span." + }, + "totals": { + "$ref": "#/components/schemas/NetworkVolumeBillingAmounts" + } + } + }, + "ClusterBillingMetadata": { + "type": "object", + "required": [ + "query", + "recordCount", + "uniqueClusterCount", + "totals" + ], + "properties": { + "query": { + "$ref": "#/components/schemas/ClusterBillingQuery" + }, + "recordCount": { + "type": "integer", + "description": "Number of records returned (buckets times distinct clusters)." + }, + "uniqueClusterCount": { + "type": "integer", + "description": "Number of distinct clusters the records span." + }, + "totals": { + "$ref": "#/components/schemas/ClusterBillingAmounts" + } + } + }, + "ListBillingResponse": { + "type": "object", + "description": "Aggregated billing records across all Runpod resources.", + "required": [ + "records", + "metadata" + ], + "properties": { + "records": { + "type": "array", + "items": { + "$ref": "#/components/schemas/BillingRecord" + } + }, + "metadata": { + "$ref": "#/components/schemas/BillingMetadata" + } + } + }, + "ListPodBillingResponse": { + "type": "object", + "description": "Billing records for pods.", + "required": [ + "records", + "metadata" + ], + "properties": { + "records": { + "type": "array", + "items": { + "$ref": "#/components/schemas/PodBillingRecord" + } + }, + "metadata": { + "$ref": "#/components/schemas/PodBillingMetadata" + } + } + }, + "ListServerlessBillingResponse": { + "type": "object", + "description": "Billing records for serverless.", + "required": [ + "records", + "metadata" + ], + "properties": { + "records": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ServerlessBillingRecord" + } + }, + "metadata": { + "$ref": "#/components/schemas/ServerlessBillingMetadata" + } + } + }, + "ListEndpointBillingResponse": { + "type": "object", + "description": "Time-bucketed Runpod public endpoint billing records plus metadata for the resolved query, record count, and total endpoint amount.\n", + "required": [ + "records", + "metadata" + ], + "properties": { + "records": { + "type": "array", + "items": { + "$ref": "#/components/schemas/EndpointBillingRecord" + } + }, + "metadata": { + "$ref": "#/components/schemas/EndpointBillingMetadata" + } + } + }, + "ListNetworkVolumeBillingResponse": { + "type": "object", + "description": "Time-bucketed network volume billing records plus metadata for the resolved query, record count, distinct volume count, and storage totals.\n", + "required": [ + "records", + "metadata" + ], + "properties": { + "records": { + "type": "array", + "items": { + "$ref": "#/components/schemas/NetworkVolumeBillingRecord" + } + }, + "metadata": { + "$ref": "#/components/schemas/NetworkVolumeBillingMetadata" + } + } + }, + "ListClusterBillingResponse": { + "type": "object", + "description": "Time-bucketed Instant Cluster billing records plus metadata for the resolved query, record count, distinct cluster count, and compute totals.\n", + "required": [ + "records", + "metadata" + ], + "properties": { + "records": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ClusterBillingRecord" + } + }, + "metadata": { + "$ref": "#/components/schemas/ClusterBillingMetadata" + } + } + }, + "ErrorResponse": { + "type": "object", + "required": [ + "title", + "status", + "detail" + ], + "properties": { + "title": { + "type": "string", + "description": "Short human-readable summary", + "examples": [ + "Not Found" + ] + }, + "status": { + "type": "integer", + "description": "HTTP status code", + "examples": [ + 404 + ] + }, + "detail": { + "type": "string", + "description": "Human-readable explanation", + "examples": [ + "pod not found" + ] + }, + "errors": { + "type": "array", + "description": "Individual request-validation failures.", + "items": { + "type": "string" + }, + "examples": [ + [ + "$: additional properties 'bogus' not allowed" + ] + ] + } + } + } + } + }, + "paths": { + "/v2/pods": { + "get": { + "operationId": "listPods", + "summary": "List pods", + "description": "Returns all pods owned by the authenticated user.", + "tags": [ + "Pods" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListPodsResponse" + }, + "examples": { + "pods": { + "summary": "Successful response", + "value": { + "pods": [ + { + "id": "7h9k2m4n6p", + "name": "pytorch-training", + "image": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1", + "args": "", + "disk": 50, + "ports": [ + "8888/http", + "22/tcp" + ], + "env": { + "MODEL_NAME": "llama-3" + }, + "registry": null, + "status": "RUNNING", + "actions": [ + "stop", + "restart", + "terminate" + ], + "mounts": { + "persistent": { + "size": 20, + "path": "/workspace" + } + }, + "gpu": { + "id": "NVIDIA GeForce RTX 4090", + "count": 1 + }, + "cloud": "SECURE", + "dataCenterId": "US-KS-2", + "template": "9x4m2p7v", + "cost": 0.44, + "locked": false, + "globalNetworking": { + "enabled": false + }, + "runtime": { + "uptime": 3600 + }, + "createdAt": "2026-06-01T12:00:00Z", + "startedAt": "2026-06-01T12:02:00Z" + } + ] + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + }, + "post": { + "operationId": "createPod", + "summary": "Create a pod", + "description": "Creates a new pod. `name` and `image` are always required; supply\nexactly one of `gpu` or `cpu` to select compute (a GPU or a CPU pod).\nRemaining container settings can be spread from a template response —\nsee `CreatePodRequest` for the full body.\n\nReturns `201` with the created pod. Provisioning is asynchronous: the\npod starts in `PROVISIONING`, transitions through `STARTING`, and\nreaches `RUNNING` once its container is healthy. Poll `getPod` (or\nwatch the pod's `status`) to observe readiness rather than assuming\nthe pod is running when this call returns.\n", + "tags": [ + "Pods" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreatePodRequest" + }, + "examples": { + "gpuPod": { + "summary": "GPU pod", + "value": { + "name": "pytorch-training", + "image": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1", + "gpu": { + "id": "NVIDIA GeForce RTX 4090", + "count": 1 + }, + "disk": 50 + } + } + } + } + } + }, + "responses": { + "201": { + "description": "Created", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Pod" + }, + "examples": { + "pod": { + "summary": "Successful response", + "value": { + "id": "7h9k2m4n6p", + "name": "pytorch-training", + "image": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1", + "args": "", + "disk": 50, + "ports": [ + "8888/http", + "22/tcp" + ], + "env": { + "MODEL_NAME": "llama-3" + }, + "registry": null, + "status": "PROVISIONING", + "actions": [ + "start", + "terminate" + ], + "mounts": { + "persistent": { + "size": 20, + "path": "/workspace" + } + }, + "gpu": { + "id": "NVIDIA GeForce RTX 4090", + "count": 1 + }, + "cloud": "SECURE", + "dataCenterId": "US-KS-2", + "template": "9x4m2p7v", + "cost": 0.44, + "locked": false, + "globalNetworking": { + "enabled": false + }, + "runtime": {}, + "createdAt": "2026-06-01T12:00:00Z", + "startedAt": null + } + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequestError" + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, + "422": { + "$ref": "#/components/responses/UnprocessableEntityError" + }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/pods/{id}": { + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "Pod identifier", + "example": "pod_abc123" + } + ], + "get": { + "operationId": "getPod", + "summary": "Get a pod", + "description": "Returns a single pod by ID.", + "tags": [ + "Pods" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Pod" + }, + "examples": { + "pod": { + "summary": "Successful response", + "value": { + "id": "7h9k2m4n6p", + "name": "pytorch-training", + "image": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1", + "args": "", + "disk": 50, + "ports": [ + "8888/http", + "22/tcp" + ], + "env": { + "MODEL_NAME": "llama-3" + }, + "registry": null, + "status": "RUNNING", + "actions": [ + "stop", + "restart", + "terminate" + ], + "mounts": { + "persistent": { + "size": 20, + "path": "/workspace" + } + }, + "gpu": { + "id": "NVIDIA GeForce RTX 4090", + "count": 1 + }, + "cloud": "SECURE", + "dataCenterId": "US-KS-2", + "template": "9x4m2p7v", + "cost": 0.44, + "locked": false, + "globalNetworking": { + "enabled": false + }, + "runtime": { + "uptime": 3600 + }, + "createdAt": "2026-06-01T12:00:00Z", + "startedAt": "2026-06-01T12:02:00Z" + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, + "404": { + "$ref": "#/components/responses/NotFoundError" + }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + }, + "patch": { + "operationId": "updatePod", + "summary": "Update a pod", + "description": "Partially updates a pod's configuration. This is a PATCH: only the\nfields present in the body are changed, and omitted fields are left\nuntouched. Use empty values only when you explicitly mean to clear a\nfield (for example, set `registry` to `null` or set `ports` to `[]`).\nSee `UpdatePodRequest` for the full body.\n\nMutable fields: `name`, `image`, `args`, `disk`, `ports`, `env`,\n`registry`, `mounts`, `locked`, and `globalNetworking`. Some changes\napply immediately while others (e.g. `globalNetworking`) take effect\non the pod's next start/restart, as noted on the individual fields.\n\nReturns `200` with the full updated pod.\n", + "tags": [ + "Pods" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdatePodRequest" + }, + "examples": { + "renamePod": { + "summary": "Rename pod", + "value": { + "name": "renamed-training-pod" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Pod" + }, + "examples": { + "pod": { + "summary": "Successful response", + "value": { + "id": "7h9k2m4n6p", + "name": "renamed-training-pod", + "image": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1", + "args": "", + "disk": 50, + "ports": [ + "8888/http", + "22/tcp" + ], + "env": { + "MODEL_NAME": "llama-3" + }, + "registry": null, + "status": "RUNNING", + "actions": [ + "stop", + "restart", + "terminate" + ], + "mounts": { + "persistent": { + "size": 20, + "path": "/workspace" + } + }, + "gpu": { + "id": "NVIDIA GeForce RTX 4090", + "count": 1 + }, + "cloud": "SECURE", + "dataCenterId": "US-KS-2", + "template": "9x4m2p7v", + "cost": 0.44, + "locked": false, + "globalNetworking": { + "enabled": false + }, + "runtime": { + "uptime": 3600 + }, + "createdAt": "2026-06-01T12:00:00Z", + "startedAt": "2026-06-01T12:02:00Z" + } + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequestError" + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, + "404": { + "$ref": "#/components/responses/NotFoundError" + }, + "422": { + "$ref": "#/components/responses/UnprocessableEntityError" + }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + }, + "delete": { + "operationId": "deletePod", + "summary": "Terminate a pod", + "description": "Permanently terminates and deletes a pod. This is irreversible:\ncompute is released, any `mounts.persistent` host-local storage is\ndestroyed with it (a `mounts.network` volume is only detached — the\nvolume itself is not deleted), and the pod no longer appears in\n`listPods`.\n", + "tags": [ + "Pods" + ], + "responses": { + "204": { + "description": "Deleted. Response has no body." + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, + "404": { + "$ref": "#/components/responses/NotFoundError" + }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/pods/{id}/logs": { + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "Pod identifier", + "example": "pod_abc123" + } + ], + "get": { + "operationId": "getPodLogs", + "summary": "Stream pod logs", + "description": "Streams pod logs as Server-Sent Events. The `source` query parameter\nselects which log source to include.\n\nThe SSE `data` payload shape is:\n`{ \"source\": \"container\", \"line\": \"...\", \"ts\": \"...\" }`.\nLog-event `id` values are the event `ts` timestamp so\nbrowser/EventSource reconnects can resume with `Last-Event-ID`.\n", + "tags": [ + "Pods" + ], + "parameters": [ + { + "$ref": "#/components/parameters/LogSourceParam" + }, + { + "$ref": "#/components/parameters/LogTail" + }, + { + "$ref": "#/components/parameters/LogSince" + }, + { + "$ref": "#/components/parameters/LogLastEventID" + } + ], + "responses": { + "200": { + "description": "Pod log event stream", + "headers": { + "Cache-Control": { + "schema": { + "type": "string" + }, + "description": "Always `no-cache` for SSE responses." + }, + "Connection": { + "schema": { + "type": "string" + }, + "description": "Always `keep-alive` to hold the SSE stream open." + }, + "X-Accel-Buffering": { + "schema": { + "type": "string" + }, + "description": "Always `no` to disable proxy buffering of the SSE stream." + } + }, + "content": { + "text/event-stream": { + "schema": { + "type": "string", + "description": "Server-Sent Events stream. Each event includes an `id:` line and a JSON `data:` payload with `source`, `line`, and `ts` fields." + }, + "examples": { + "logLine": { + "summary": "Successful response", + "value": "id: 2026-06-01T12:02:03Z/000000000001\ndata: {\"ts\":\"2026-06-01T12:02:03Z\",\"source\":\"container\",\"line\":\"Model loaded.\"}\n" + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, + "404": { + "$ref": "#/components/responses/NotFoundError" + }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/pods/{id}/action": { + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "example": "pod_abc123" + } + ], + "post": { + "operationId": "podAction", + "summary": "Trigger a pod state transition", + "description": "Triggers a state transition on a pod. Send a JSON body with a single\n`action` field, e.g. `{ \"action\": \"stop\" }`.\n\nValid actions:\n- `start` — boot a stopped pod (`EXITED` or `ERROR`) back toward\n `RUNNING`.\n- `stop` — stop a running or provisioning pod, releasing GPU/CPU\n compute while keeping its disk. The pod moves to `EXITED`.\n- `restart` — restart a `RUNNING` pod's container in place.\n- `terminate` — permanently delete the pod and release its resources\n (equivalent to `deletePod`).\n\nWhich actions are valid depends on the pod's current status, and the\ncurrently permitted set is published in the pod's `actions` field:\n`RUNNING` allows `stop`/`restart`/`terminate`; `EXITED` and `ERROR`\nallow `start`/`terminate`; `PROVISIONING` and `STARTING` allow\n`stop`/`terminate`.\n\n`start`, `stop`, and `restart` return `200` with the updated pod.\n`terminate` returns `204` with no body. Requesting an action that is\nnot valid for the pod's current status returns `409`.\n", + "tags": [ + "Pods" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PodActionRequest" + }, + "examples": { + "startPod": { + "summary": "Start pod", + "value": { + "action": "start" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Action applied — returns updated pod", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Pod" + }, + "examples": { + "pod": { + "summary": "Successful response", + "value": { + "id": "7h9k2m4n6p", + "name": "pytorch-training", + "image": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1", + "args": "", + "disk": 50, + "ports": [ + "8888/http", + "22/tcp" + ], + "env": { + "MODEL_NAME": "llama-3" + }, + "registry": null, + "status": "RUNNING", + "actions": [ + "stop", + "restart", + "terminate" + ], + "mounts": { + "persistent": { + "size": 20, + "path": "/workspace" + } + }, + "gpu": { + "id": "NVIDIA GeForce RTX 4090", + "count": 1 + }, + "cloud": "SECURE", + "dataCenterId": "US-KS-2", + "template": "9x4m2p7v", + "cost": 0.44, + "locked": false, + "globalNetworking": { + "enabled": false + }, + "runtime": { + "uptime": 3600 + }, + "createdAt": "2026-06-01T12:00:00Z", + "startedAt": "2026-06-01T12:02:00Z" + } + } + } + } + } + }, + "204": { + "description": "Only returned when `action=terminate`; response has no body." + }, + "400": { + "$ref": "#/components/responses/BadRequestError" + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, + "404": { + "$ref": "#/components/responses/NotFoundError" + }, + "409": { + "description": "Action not valid for current pod status", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "422": { + "$ref": "#/components/responses/UnprocessableEntityError" + }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/serverless": { + "get": { + "operationId": "listEndpoints", + "summary": "List serverless endpoints", + "description": "Returns all serverless endpoints owned by the authenticated user.", + "tags": [ + "Serverless" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListEndpointsResponse" + }, + "examples": { + "endpoints": { + "summary": "Successful response", + "value": { + "endpoints": [ + { + "id": "4m7x2k9q", + "name": "image-generator", + "type": "QUEUE_BASED", + "requestUrls": { + "run": "https://api.runpod.ai/v2/4m7x2k9q/run", + "runSync": "https://api.runpod.ai/v2/4m7x2k9q/runsync" + }, + "image": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1", + "args": "", + "disk": 20, + "ports": [ + "8000/http" + ], + "env": { + "MODEL_NAME": "sdxl" + }, + "registry": null, + "gpu": { + "pools": [ + "ADA_24" + ], + "count": 1 + }, + "workers": { + "min": 0, + "max": 5 + }, + "scaling": { + "type": "QUEUE_DELAY", + "value": 4, + "idleTimeout": 5 + }, + "dataCenterIds": [ + "US-KS-2" + ], + "networkVolumes": [ + "2q9m7x4c" + ], + "timeout": 300000, + "flashboot": "OFF", + "createdAt": "2026-06-01T12:00:00Z" + } + ] + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + }, + "post": { + "operationId": "createEndpoint", + "summary": "Create a serverless endpoint", + "description": "Creates a serverless endpoint. Specify `gpu` for compute (CPU\nserverless endpoints are read-only). Container settings can be spread\nfrom a template response — see `CreateEndpointRequest` for the full\nbody.\n\nReturns `201` with the created endpoint. The endpoint can accept jobs\nimmediately, but starts with no active workers unless `workers.min`\nis greater than 0. Workers are provisioned on demand and autoscaled\nbetween `workers.min` and `workers.max` according to the `scaling`\npolicy, so the first request to an idle endpoint may incur cold-start\nlatency while a worker pulls its image and boots.\n", + "tags": [ + "Serverless" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateEndpointRequest" + }, + "examples": { + "serverlessEndpoint": { + "summary": "Serverless endpoint", + "value": { + "name": "image-generator", + "image": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1", + "gpu": { + "pools": [ + "ADA_24" + ], + "count": 1 + }, + "workers": { + "min": 0, + "max": 5 + }, + "scaling": { + "type": "QUEUE_DELAY", + "value": 4, + "idleTimeout": 5 + }, + "dataCenterIds": [ + "US-KS-2" + ], + "timeout": 300000 + } + } + } + } + } + }, + "responses": { + "201": { + "description": "Created", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Endpoint" + }, + "examples": { + "endpoint": { + "summary": "Successful response", + "value": { + "id": "4m7x2k9q", + "name": "image-generator", + "type": "QUEUE_BASED", + "requestUrls": { + "run": "https://api.runpod.ai/v2/4m7x2k9q/run", + "runSync": "https://api.runpod.ai/v2/4m7x2k9q/runsync" + }, + "image": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1", + "args": "", + "disk": 20, + "ports": [ + "8000/http" + ], + "env": { + "MODEL_NAME": "sdxl" + }, + "registry": null, + "gpu": { + "pools": [ + "ADA_24" + ], + "count": 1 + }, + "workers": { + "min": 0, + "max": 5 + }, + "scaling": { + "type": "QUEUE_DELAY", + "value": 4, + "idleTimeout": 5 + }, + "dataCenterIds": [ + "US-KS-2" + ], + "networkVolumes": [ + "2q9m7x4c" + ], + "timeout": 300000, + "flashboot": "OFF", + "createdAt": "2026-06-01T12:00:00Z" + } + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequestError" + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, + "422": { + "$ref": "#/components/responses/UnprocessableEntityError" + }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/serverless/{id}": { + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "Serverless endpoint identifier", + "example": "ep_abc123" + } + ], + "get": { + "operationId": "getEndpoint", + "summary": "Get a serverless endpoint", + "description": "Returns a single serverless endpoint by ID.", + "tags": [ + "Serverless" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Endpoint" + }, + "examples": { + "endpoint": { + "summary": "Successful response", + "value": { + "id": "4m7x2k9q", + "name": "image-generator", + "type": "LOAD_BALANCING", + "requestUrls": { + "base": "https://4m7x2k9q.api.runpod.ai" + }, + "image": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1", + "args": "", + "disk": 20, + "ports": [ + "8000/http" + ], + "env": { + "MODEL_NAME": "sdxl" + }, + "registry": null, + "gpu": { + "pools": [ + "ADA_24" + ], + "count": 1 + }, + "workers": { + "min": 0, + "max": 5 + }, + "scaling": { + "type": "QUEUE_DELAY", + "value": 4, + "idleTimeout": 5 + }, + "dataCenterIds": [ + "US-KS-2" + ], + "networkVolumes": [ + "2q9m7x4c" + ], + "timeout": 300000, + "flashboot": "OFF", + "createdAt": "2026-06-01T12:00:00Z" + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, + "404": { + "$ref": "#/components/responses/NotFoundError" + }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + }, + "patch": { + "operationId": "updateEndpoint", + "summary": "Update a serverless endpoint", + "description": "Partially updates a serverless endpoint. This is a PATCH: only the\nfields present in the body are changed; omitted fields are left\nuntouched. See `UpdateEndpointRequest` for the full body.\n\nMutable fields: `name`, `gpu`, `workers` (`min`/`max`), `scaling`\n(`type`/`value`/`idleTimeout`), `dataCenterIds`, `networkVolumes`,\n`timeout`, `flashboot`, and the container settings (`image`, `args`,\n`disk`, `ports`, `env`, `registry`).\n\nReturns `200` with the full updated endpoint. Effect timing differs\nby field: scaling and worker-bound settings (`workers`, `scaling`,\n`timeout`) are applied to the autoscaler promptly, while\ncontainer-affecting changes (e.g. `image`, `env`) create a new\nendpoint release that rolls out as workers cycle — in-flight workers\nkeep the previous version until they are replaced. Track rollout via\n`listEndpointReleases`.\n", + "tags": [ + "Serverless" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateEndpointRequest" + }, + "examples": { + "scaleEndpoint": { + "summary": "Scale endpoint", + "value": { + "workers": { + "min": 1, + "max": 10 + }, + "scaling": { + "type": "REQUEST_COUNT", + "value": 8, + "idleTimeout": 10 + } + } + } + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Endpoint" + }, + "examples": { + "endpoint": { + "summary": "Successful response", + "value": { + "id": "4m7x2k9q", + "name": "image-generator", + "type": "QUEUE_BASED", + "requestUrls": { + "run": "https://api.runpod.ai/v2/4m7x2k9q/run", + "runSync": "https://api.runpod.ai/v2/4m7x2k9q/runsync" + }, + "image": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1", + "args": "", + "disk": 20, + "ports": [ + "8000/http" + ], + "env": { + "MODEL_NAME": "sdxl" + }, + "registry": null, + "gpu": { + "pools": [ + "ADA_24" + ], + "count": 1 + }, + "workers": { + "min": 1, + "max": 10 + }, + "scaling": { + "type": "REQUEST_COUNT", + "value": 8, + "idleTimeout": 10 + }, + "dataCenterIds": [ + "US-KS-2" + ], + "networkVolumes": [ + "2q9m7x4c" + ], + "timeout": 300000, + "flashboot": "OFF", + "createdAt": "2026-06-01T12:00:00Z" + } + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequestError" + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, + "404": { + "$ref": "#/components/responses/NotFoundError" + }, + "422": { + "$ref": "#/components/responses/UnprocessableEntityError" + }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + }, + "delete": { + "operationId": "deleteEndpoint", + "summary": "Delete a serverless endpoint", + "description": "Permanently deletes a serverless endpoint and its bound template.\nThis is irreversible: all workers are terminated and any queued or\nin-progress jobs are cancelled.\n", + "tags": [ + "Serverless" + ], + "responses": { + "204": { + "description": "Deleted. Response has no body." + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, + "404": { + "$ref": "#/components/responses/NotFoundError" + }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/serverless/{id}/workers": { + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "Serverless endpoint identifier", + "example": "ep_abc123" + } + ], + "get": { + "operationId": "listEndpointWorkers", + "summary": "List serverless endpoint workers", + "description": "Lists the active workers for a serverless endpoint.\n\n**Returns.** A `200` with a `ListEndpointWorkersResponse`: a\n`workers` array (one entry per active worker, each carrying its `id`,\n`status`, and runtime details) plus a `summary` of worker counts\ngrouped by status. Only currently active workers are included;\nscaled-down workers are not returned.\n\n**How `status` is determined.** Each worker's `status` is derived by\nreconciling the worker pod's lifecycle status with the endpoint's\nlive job-queue view (which workers are actively serving requests).\nWhen the job-queue view is unavailable, the response degrades\ngracefully: the shape is unchanged, but each `status` and the summary\ncounts fall back to pod lifecycle alone.\n", + "tags": [ + "Serverless" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListEndpointWorkersResponse" + }, + "examples": { + "workers": { + "summary": "Successful response", + "value": { + "endpointVersion": 4, + "summary": { + "running": 1, + "idle": 1, + "initializing": 0, + "throttled": 0, + "unhealthy": 0, + "total": 2 + }, + "workers": [ + { + "id": "8g3n5t6r", + "status": "RUNNING", + "isStale": false, + "version": 4, + "gpuCount": 1, + "image": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1", + "uptimeSeconds": 3600, + "gpuTypeId": "NVIDIA GeForce RTX 4090", + "dataCenterId": "US-KS-2", + "startedAt": "2026-06-01T12:05:00Z" + } + ] + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, + "404": { + "$ref": "#/components/responses/NotFoundError" + }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/serverless/{id}/releases": { + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "Serverless endpoint identifier", + "example": "ep_abc123" + } + ], + "get": { + "operationId": "listEndpointReleases", + "summary": "List serverless endpoint releases", + "description": "Returns the endpoint's release history (newest first) plus a rollout\nsummary of how many workers are running the current version. Each\nrelease is a versioned configuration snapshot with a `diff` of what\nchanged; build-driven releases carry a `buildId` (fetch build detail via\nthe builds sub-routes).\n", + "tags": [ + "Serverless" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListEndpointReleasesResponse" + }, + "examples": { + "releases": { + "summary": "Successful response", + "value": { + "endpointVersion": 4, + "rollout": { + "inProgress": true, + "workersOnLatest": 1, + "workersTotal": 2, + "percentOnLatest": 50 + }, + "releases": [ + { + "id": "5r9x2m7q", + "version": 4, + "source": "MANUAL", + "buildId": null, + "createdByUserId": null, + "workerCount": 2, + "createdAt": "2026-06-01T12:10:00Z", + "diff": [ + { + "field": "workers.max", + "old": 5, + "new": 10 + } + ] + } + ] + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, + "404": { + "$ref": "#/components/responses/NotFoundError" + }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/serverless/{id}/workers/{workerId}/logs": { + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "Serverless endpoint identifier", + "example": "ep_abc123" + }, + { + "name": "workerId", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "Worker identifier (from GET /v2/serverless/{id}/workers)", + "example": "worker_abc" + } + ], + "get": { + "operationId": "getWorkerLogs", + "summary": "Stream serverless worker logs", + "description": "Streams a serverless worker's logs as Server-Sent Events. The `source`\nquery parameter selects which log source to include.\n\nThe SSE `data` payload shape is:\n`{ \"source\": \"container\", \"line\": \"...\", \"ts\": \"...\" }`.\nLog-event `id` values are the event `ts` timestamp so browser/EventSource\nreconnects can resume with `Last-Event-ID`.\n", + "tags": [ + "Serverless" + ], + "parameters": [ + { + "$ref": "#/components/parameters/LogSourceParam" + }, + { + "$ref": "#/components/parameters/LogTail" + }, + { + "$ref": "#/components/parameters/LogSince" + }, + { + "$ref": "#/components/parameters/LogLastEventID" + } + ], + "responses": { + "200": { + "description": "Worker log event stream", + "headers": { + "Cache-Control": { + "schema": { + "type": "string" + }, + "description": "Always `no-cache` for SSE responses." + }, + "Connection": { + "schema": { + "type": "string" + }, + "description": "Always `keep-alive` to hold the SSE stream open." + }, + "X-Accel-Buffering": { + "schema": { + "type": "string" + }, + "description": "Always `no` to disable proxy buffering of the SSE stream." + } + }, + "content": { + "text/event-stream": { + "schema": { + "type": "string", + "description": "Server-Sent Events stream. Each event includes an `id:` line and a JSON `data:` payload with `source`, `line`, and `ts` fields." + }, + "examples": { + "logLine": { + "summary": "Successful response", + "value": "id: 2026-06-01T12:05:04Z/000000000042\ndata: {\"ts\":\"2026-06-01T12:05:04Z\",\"source\":\"container\",\"line\":\"Worker ready.\"}\n" + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, + "404": { + "$ref": "#/components/responses/NotFoundError" + }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/templates": { + "get": { + "operationId": "listTemplates", + "summary": "List templates", + "description": "Returns all templates owned by the authenticated user.", + "tags": [ + "Templates" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListTemplatesResponse" + }, + "examples": { + "templates": { + "summary": "Successful response", + "value": { + "templates": [ + { + "id": "9x4m2p7v", + "name": "PyTorch GPU Template", + "image": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1", + "args": "", + "disk": 50, + "mounts": { + "persistent": { + "size": 20, + "path": "/workspace" + } + }, + "ports": [ + "8888/http" + ], + "env": { + "JUPYTER_ENABLE_LAB": "yes" + }, + "registry": null, + "serverless": false, + "public": false, + "category": "NVIDIA" + } + ] + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + }, + "post": { + "operationId": "createTemplate", + "summary": "Create a template", + "description": "Creates a reusable container-configuration preset — image, disk,\nports, env, registry, and mount settings — for pods and serverless\nendpoints. `createPod` and `createEndpoint` don't take a template ID;\ninstead, spread a template's fields into the request body directly.\nReturns the created template.\n", + "tags": [ + "Templates" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateTemplateRequest" + }, + "examples": { + "podTemplate": { + "summary": "Pod template", + "value": { + "name": "PyTorch GPU Template", + "image": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1", + "category": "NVIDIA", + "disk": 50, + "ports": [ + "8888/http" + ], + "env": { + "JUPYTER_ENABLE_LAB": "yes" + }, + "mounts": { + "persistent": { + "size": 20, + "path": "/workspace" + } + }, + "serverless": false, + "public": false + } + } + } + } + } + }, + "responses": { + "201": { + "description": "Created", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Template" + }, + "examples": { + "template": { + "summary": "Successful response", + "value": { + "id": "9x4m2p7v", + "name": "PyTorch GPU Template", + "image": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1", + "args": "", + "disk": 50, + "mounts": { + "persistent": { + "size": 20, + "path": "/workspace" + } + }, + "ports": [ + "8888/http" + ], + "env": { + "JUPYTER_ENABLE_LAB": "yes" + }, + "registry": null, + "serverless": false, + "public": false, + "category": "NVIDIA" + } + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequestError" + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, + "422": { + "$ref": "#/components/responses/UnprocessableEntityError" + }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/templates/{id}": { + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "example": "tpl_abc" + } + ], + "get": { + "operationId": "getTemplate", + "summary": "Get a template", + "description": "Returns the full configuration of a single template by ID.", + "tags": [ + "Templates" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Template" + }, + "examples": { + "template": { + "summary": "Successful response", + "value": { + "id": "9x4m2p7v", + "name": "PyTorch GPU Template", + "image": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1", + "args": "", + "disk": 50, + "mounts": { + "persistent": { + "size": 20, + "path": "/workspace" + } + }, + "ports": [ + "8888/http" + ], + "env": { + "JUPYTER_ENABLE_LAB": "yes" + }, + "registry": null, + "serverless": false, + "public": false, + "category": "NVIDIA" + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, + "404": { + "$ref": "#/components/responses/NotFoundError" + }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + }, + "patch": { + "operationId": "updateTemplate", + "summary": "Update a template", + "description": "Partially updates a template. This is a PATCH: only the fields\npresent in the body are changed; omitted fields are left untouched.\nSee `UpdateTemplateRequest` for the full body.\n\nMutable fields: `name`, `image`, `args`, `disk`, `ports`, `env`,\n`registry`, `mounts`, `serverless`, `public`, and `category`.\n\nOnly the template's owner can update it (authenticated via the\nrequest's API key); other users' templates are neither visible nor\nmutable. Returns `200` with the full updated template. Pods and\nendpoints already created from this template are not changed\nretroactively — the template is a snapshot applied at creation time.\n", + "tags": [ + "Templates" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateTemplateRequest" + }, + "examples": { + "renameTemplate": { + "summary": "Rename template", + "value": { + "name": "Renamed PyTorch Template" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Template" + }, + "examples": { + "template": { + "summary": "Successful response", + "value": { + "id": "9x4m2p7v", + "name": "Renamed PyTorch Template", + "image": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1", + "args": "", + "disk": 50, + "mounts": { + "persistent": { + "size": 20, + "path": "/workspace" + } + }, + "ports": [ + "8888/http" + ], + "env": { + "JUPYTER_ENABLE_LAB": "yes" + }, + "registry": null, + "serverless": false, + "public": false, + "category": "NVIDIA" + } + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequestError" + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, + "404": { + "$ref": "#/components/responses/NotFoundError" + }, + "422": { + "$ref": "#/components/responses/UnprocessableEntityError" + }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + }, + "delete": { + "operationId": "deleteTemplate", + "summary": "Delete a template", + "description": "Permanently deletes a template by ID. Rejected if the template is\ncurrently referenced by a pod (see that pod's `template` field) or\nbound to a serverless endpoint.\n", + "tags": [ + "Templates" + ], + "responses": { + "204": { + "description": "Deleted. Response has no body." + }, + "400": { + "description": "Template is in use by a pod or serverless endpoint and cannot be deleted", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, + "404": { + "$ref": "#/components/responses/NotFoundError" + }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/network-volumes": { + "get": { + "operationId": "listNetworkVolumes", + "summary": "List network volumes", + "description": "Returns all network volumes owned by the authenticated user.", + "tags": [ + "Network Volumes" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListNetworkVolumesResponse" + }, + "examples": { + "networkVolumes": { + "summary": "Successful response", + "value": { + "networkVolumes": [ + { + "id": "2q9m7x4c", + "name": "training-dataset", + "size": 100, + "dataCenter": "US-KS-2", + "type": "HIGH_PERFORMANCE" + } + ] + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + }, + "post": { + "operationId": "createNetworkVolume", + "summary": "Create a network volume", + "description": "Provisions a new network volume — persistent, network-attached\nstorage that can be mounted into pods and serverless workers.\nRequired inputs are `name`, `size` (in GB), and `dataCenter`; an\noptional `type` selects the storage tier and is immutable after\ncreation. See `CreateNetworkVolumeRequest` for the size bounds and\ntier options.\n\nThis creates a billable persistent resource that keeps incurring\nstorage charges until it is deleted. Returns `201` with the created\nnetwork volume, including its assigned `id`.\n", + "tags": [ + "Network Volumes" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateNetworkVolumeRequest" + }, + "examples": { + "networkVolume": { + "summary": "Network volume", + "value": { + "name": "training-dataset", + "dataCenter": "US-KS-2", + "size": 50, + "type": "HIGH_PERFORMANCE" + } + } + } + } + } + }, + "responses": { + "201": { + "description": "Created", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NetworkVolume" + }, + "examples": { + "networkVolume": { + "summary": "Successful response", + "value": { + "id": "2q9m7x4c", + "name": "training-dataset", + "size": 50, + "dataCenter": "US-KS-2", + "type": "HIGH_PERFORMANCE" + } + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequestError" + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, + "422": { + "$ref": "#/components/responses/UnprocessableEntityError" + }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/network-volumes/{id}": { + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "Network volume identifier", + "example": "agv6w2qcg7" + } + ], + "get": { + "operationId": "getNetworkVolume", + "summary": "Get a network volume", + "description": "Returns a single network volume by ID.", + "tags": [ + "Network Volumes" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NetworkVolume" + }, + "examples": { + "networkVolume": { + "summary": "Successful response", + "value": { + "id": "2q9m7x4c", + "name": "training-dataset", + "size": 100, + "dataCenter": "US-KS-2", + "type": "HIGH_PERFORMANCE" + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, + "404": { + "$ref": "#/components/responses/NotFoundError" + }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + }, + "patch": { + "operationId": "updateNetworkVolume", + "summary": "Update a network volume", + "description": "Updates mutable fields on a network volume. Only provided fields are changed.\nNote: `size` may only increase; attempts to reduce size will be rejected.\n", + "tags": [ + "Network Volumes" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateNetworkVolumeRequest" + }, + "examples": { + "resizeNetworkVolume": { + "summary": "Resize network volume", + "value": { + "size": 200 + } + } + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NetworkVolume" + }, + "examples": { + "networkVolume": { + "summary": "Successful response", + "value": { + "id": "2q9m7x4c", + "name": "training-dataset", + "size": 200, + "dataCenter": "US-KS-2", + "type": "HIGH_PERFORMANCE" + } + } + } + } + } + }, + "400": { + "description": "Invalid request body or size decrease attempted", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, + "404": { + "$ref": "#/components/responses/NotFoundError" + }, + "422": { + "$ref": "#/components/responses/UnprocessableEntityError" + }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + }, + "delete": { + "operationId": "deleteNetworkVolume", + "summary": "Delete a network volume", + "description": "Permanently deletes a network volume and releases its storage.", + "tags": [ + "Network Volumes" + ], + "responses": { + "204": { + "description": "Deleted. Response has no body." + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, + "404": { + "$ref": "#/components/responses/NotFoundError" + }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/registries": { + "get": { + "operationId": "listRegistries", + "summary": "List container registries", + "description": "Returns all container registry credentials owned by the authenticated user.", + "tags": [ + "Registries" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListRegistriesResponse" + }, + "examples": { + "registries": { + "summary": "Successful response", + "value": { + "registries": [ + { + "id": "6n2k8v4d", + "name": "dockerhub-private" + } + ] + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + }, + "post": { + "operationId": "createRegistry", + "summary": "Create a container registry credential", + "description": "Stores credentials for a private container registry. Credentials are write-only.", + "tags": [ + "Registries" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateRegistryRequest" + }, + "examples": { + "dockerHubRegistry": { + "summary": "Docker Hub registry", + "value": { + "name": "dockerhub-private", + "username": "runpod-user", + "password": "correct-horse-battery-staple" + } + } + } + } + } + }, + "responses": { + "201": { + "description": "Created", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Registry" + }, + "examples": { + "registry": { + "summary": "Successful response", + "value": { + "id": "6n2k8v4d", + "name": "dockerhub-private" + } + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequestError" + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, + "422": { + "$ref": "#/components/responses/UnprocessableEntityError" + }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/registries/{id}": { + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "example": "reg_abc" + } + ], + "get": { + "operationId": "getRegistry", + "summary": "Get a container registry credential", + "description": "Returns a single container registry credential by ID. `username` and\n`password` are never included in the response — credentials are\nwrite-only, matching `createRegistry`.\n", + "tags": [ + "Registries" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Registry" + }, + "examples": { + "registry": { + "summary": "Successful response", + "value": { + "id": "6n2k8v4d", + "name": "dockerhub-private" + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, + "404": { + "$ref": "#/components/responses/NotFoundError" + }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + }, + "delete": { + "operationId": "deleteRegistry", + "summary": "Delete a container registry credential", + "description": "Permanently deletes a container registry credential by ID. Rejected\nif any pod currently uses this credential to pull its image.\nTemplates that reference it are not part of that check — they\nsilently lose the reference (`registry` becomes null) instead of\nblocking the delete.\n", + "tags": [ + "Registries" + ], + "responses": { + "204": { + "description": "Deleted. Response has no body." + }, + "400": { + "description": "Registry credential is in use by a pod and cannot be deleted", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, + "404": { + "$ref": "#/components/responses/NotFoundError" + }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/registries/delegations": { + "get": { + "operationId": "listDelegations", + "summary": "List all ECR delegations", + "tags": [ + "Registries" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListDelegationsResponse" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + }, + "post": { + "operationId": "createDelegation", + "summary": "Register an ECR delegation", + "tags": [ + "Registries" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateDelegationRequest" + } + } + } + }, + "responses": { + "201": { + "description": "Delegation created", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EcrDelegation" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/registries/delegations/{id}": { + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "example": "deleg_abc" + } + ], + "delete": { + "operationId": "revokeDelegation", + "summary": "Revoke an ECR delegation", + "tags": [ + "Registries" + ], + "responses": { + "204": { + "description": "Delegation revoked" + }, + "404": { + "description": "Delegation not found", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/catalog/gpus": { + "get": { + "operationId": "listGpuTypes", + "summary": "List GPU types", + "description": "Returns available GPU types with pricing. Availability is included only when requested with include=AVAILABILITY.", + "tags": [ + "Catalog" + ], + "parameters": [ + { + "$ref": "#/components/parameters/CatalogIncludeParam" + }, + { + "$ref": "#/components/parameters/GpuProductFilter" + }, + { + "$ref": "#/components/parameters/GpuCountFilter" + }, + { + "$ref": "#/components/parameters/GpuCloudFilter" + }, + { + "$ref": "#/components/parameters/MinCudaVersionFilter" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListGpuTypesResponse" + }, + "examples": { + "gpus": { + "summary": "Successful response", + "value": { + "gpus": [ + { + "id": "NVIDIA GeForce RTX 4090", + "name": "RTX 4090", + "pool": "ADA_24", + "manufacturer": "NVIDIA", + "memory": 24, + "secure": true, + "community": true, + "price": { + "secure": 0.44, + "community": 0.31 + }, + "maxCount": { + "secure": 8, + "community": 4 + }, + "availability": "HIGH", + "dataCenters": [ + { + "id": "US-KS-2", + "name": "US Kansas 2", + "availability": "HIGH" + } + ] + } + ] + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/catalog/gpus/{id}": { + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "example": "NVIDIA GeForce RTX 4090" + } + ], + "get": { + "operationId": "getGpuType", + "summary": "Get a GPU type", + "description": "Returns a single GPU type with pricing. Availability details are included only when requested with include=AVAILABILITY.", + "tags": [ + "Catalog" + ], + "parameters": [ + { + "$ref": "#/components/parameters/CatalogIncludeParam" + }, + { + "$ref": "#/components/parameters/GpuProductFilter" + }, + { + "$ref": "#/components/parameters/GpuCountFilter" + }, + { + "$ref": "#/components/parameters/GpuCloudFilter" + }, + { + "$ref": "#/components/parameters/MinCudaVersionFilter" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GpuType" + }, + "examples": { + "gpu": { + "summary": "Successful response", + "value": { + "id": "NVIDIA GeForce RTX 4090", + "name": "RTX 4090", + "pool": "ADA_24", + "manufacturer": "NVIDIA", + "memory": 24, + "secure": true, + "community": true, + "price": { + "secure": 0.44, + "community": 0.31 + }, + "maxCount": { + "secure": 8, + "community": 4 + }, + "availability": "HIGH", + "dataCenters": [ + { + "id": "US-KS-2", + "name": "US Kansas 2", + "availability": "HIGH" + } + ] + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, + "404": { + "$ref": "#/components/responses/NotFoundError" + }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/catalog/cpus": { + "get": { + "operationId": "listCpuTypes", + "summary": "List CPU types", + "description": "Returns available CPU flavors. Availability is included only when requested with include=AVAILABILITY.", + "tags": [ + "Catalog" + ], + "parameters": [ + { + "$ref": "#/components/parameters/CatalogIncludeParam" + }, + { + "$ref": "#/components/parameters/CpuProductFilter" + }, + { + "$ref": "#/components/parameters/CpuVCPUCountFilter" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListCpuTypesResponse" + }, + "examples": { + "cpus": { + "summary": "Successful response", + "value": { + "cpus": [ + { + "id": "cpu3c-2-4", + "name": "Compute-Optimized", + "group": "Gen 3", + "vcpu": { + "min": 2, + "max": 32 + }, + "ramGbPerVcpu": 2.5, + "price": { + "securePerVcpu": 0.04, + "serverlessPerVcpu": 0.03 + }, + "availability": "MEDIUM", + "dataCenters": [ + { + "id": "US-KS-2", + "name": "US Kansas 2", + "availability": "MEDIUM" + } + ] + } + ] + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/catalog/cpus/{id}": { + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "example": "cpu5c" + } + ], + "get": { + "operationId": "getCpuType", + "summary": "Get a CPU type", + "description": "Returns a single CPU type with pricing. Availability details are included only when requested with include=AVAILABILITY.", + "tags": [ + "Catalog" + ], + "parameters": [ + { + "$ref": "#/components/parameters/CatalogIncludeParam" + }, + { + "$ref": "#/components/parameters/CpuProductFilter" + }, + { + "$ref": "#/components/parameters/CpuVCPUCountFilter" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CpuType" + }, + "examples": { + "cpu": { + "summary": "Successful response", + "value": { + "id": "cpu3c-2-4", + "name": "Compute-Optimized", + "group": "Gen 3", + "vcpu": { + "min": 2, + "max": 32 + }, + "ramGbPerVcpu": 2.5, + "price": { + "securePerVcpu": 0.04, + "serverlessPerVcpu": 0.03 + }, + "availability": "MEDIUM", + "dataCenters": [ + { + "id": "US-KS-2", + "name": "US Kansas 2", + "availability": "MEDIUM" + } + ] + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, + "404": { + "$ref": "#/components/responses/NotFoundError" + }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/catalog/datacenters": { + "get": { + "operationId": "listDataCenters", + "summary": "List data centers", + "description": "Returns available data center locations with region, compliance, supported network volume tiers, and global networking support. Use include=GPU_AVAILABILITY or include=CPU_AVAILABILITY to add per-resource availability arrays to each data center. The regions, networkVolumeTypes, compliance, and globalNetwork query parameters filter the list before it is returned.\n", + "tags": [ + "Catalog" + ], + "parameters": [ + { + "name": "include", + "in": "query", + "required": false, + "description": "Comma-separated optional expansions. Supported value: GPU_AVAILABILITY, CPU_AVAILABILITY.", + "style": "form", + "explode": false, + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/DataCenterInclude" + }, + "example": [ + "GPU_AVAILABILITY" + ] + } + }, + { + "name": "regions", + "in": "query", + "required": false, + "description": "Comma-separated DataCenterRegion enum values. Values within this filter use OR semantics. Different filter families combine with AND.", + "style": "form", + "explode": false, + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/DataCenterRegion" + }, + "example": [ + "EUROPE", + "ASIA" + ] + } + }, + { + "name": "networkVolumeTypes", + "in": "query", + "required": false, + "description": "Comma-separated volume types. Supported values: STANDARD, HIGH_PERFORMANCE. Values within this filter use AND semantics; volumes=STANDARD,HIGH_PERFORMANCE requires both storage types. Different filter families combine with AND.", + "style": "form", + "explode": false, + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/VolumeType" + }, + "example": [ + "STANDARD", + "HIGH_PERFORMANCE" + ] + } + }, + { + "name": "compliance", + "in": "query", + "required": false, + "description": "Comma-separated Compliance enum values. Values within this filter use AND semantics; compliance=GDPR,SOC_2_TYPE_2 requires both certifications. Different filter families combine with AND.", + "style": "form", + "explode": false, + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Compliance" + }, + "example": [ + "GDPR", + "SOC_2_TYPE_2" + ] + } + }, + { + "name": "globalNetwork", + "in": "query", + "required": false, + "description": "Filter by global networking support. true returns only data centers that support global networking; false only those that do not. Different filter families combine with AND.", + "schema": { + "type": "boolean" + }, + "example": true + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListDataCentersResponse" + }, + "examples": { + "dataCenters": { + "summary": "Successful response", + "value": { + "dataCenters": [ + { + "id": "US-KS-2", + "name": "US Kansas 2", + "region": "NORTH_AMERICA", + "globalNetwork": true, + "networkVolumeTypes": [ + "STANDARD", + "HIGH_PERFORMANCE" + ], + "compliance": [ + "SOC_2_TYPE_2", + "ISO_IEC_27001" + ], + "gpuAvailability": [ + { + "id": "NVIDIA GeForce RTX 4090", + "name": "RTX 4090", + "availability": "HIGH" + } + ], + "cpuAvailability": [ + { + "id": "cpu3c-2-4", + "name": "Compute-Optimized", + "availability": "MEDIUM" + } + ] + } + ] + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/catalog/datacenters/{id}": { + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "example": "US-CA-2" + } + ], + "get": { + "operationId": "getDataCenter", + "summary": "Get a data center", + "description": "Returns a single data center. Availability is included only when requested with include=GPU_AVAILABILITY or include=CPU_AVAILABILITY.", + "tags": [ + "Catalog" + ], + "parameters": [ + { + "name": "include", + "in": "query", + "required": false, + "description": "Comma-separated optional expansions. Supported value: GPU_AVAILABILITY, CPU_AVAILABILITY.", + "style": "form", + "explode": false, + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/DataCenterInclude" + }, + "example": [ + "GPU_AVAILABILITY" + ] + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DataCenter" + }, + "examples": { + "dataCenter": { + "summary": "Successful response", + "value": { + "id": "US-KS-2", + "name": "US Kansas 2", + "region": "NORTH_AMERICA", + "globalNetwork": true, + "networkVolumeTypes": [ + "STANDARD", + "HIGH_PERFORMANCE" + ], + "compliance": [ + "SOC_2_TYPE_2", + "ISO_IEC_27001" + ], + "gpuAvailability": [ + { + "id": "NVIDIA GeForce RTX 4090", + "name": "RTX 4090", + "availability": "HIGH" + } + ], + "cpuAvailability": [ + { + "id": "cpu3c-2-4", + "name": "Compute-Optimized", + "availability": "MEDIUM" + } + ] + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, + "404": { + "$ref": "#/components/responses/NotFoundError" + }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/billing": { + "get": { + "operationId": "listBilling", + "summary": "Get aggregated billing history", + "description": "Returns time-bucketed total spend across all billable Runpod resources for the authenticated user. Use startTime/endTime with bucketSize for an explicit range, or lastN with bucketSize for the most recent buckets. Each record reports one bucket's total plus pod, serverless, storage, public endpoint, and Instant Cluster cost components. The metadata block echoes the resolved query window, record count, and totals across all returned buckets.\n", + "tags": [ + "Billing" + ], + "parameters": [ + { + "$ref": "#/components/parameters/BillingStartTime" + }, + { + "$ref": "#/components/parameters/BillingEndTime" + }, + { + "$ref": "#/components/parameters/BillingBucketSize" + }, + { + "$ref": "#/components/parameters/BillingLastN" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListBillingResponse" + }, + "examples": { + "billing": { + "summary": "Successful response", + "value": { + "records": [ + { + "startTime": "2026-06-01T00:00:00Z", + "endTime": "2026-06-02T00:00:00Z", + "totalAmount": 42.34, + "podGpuAmount": 18.2, + "podCpuAmount": 0, + "podDiskAmount": 1.1, + "serverlessGpuAmount": 12.6, + "serverlessCpuAmount": 0, + "serverlessDiskAmount": 0.44, + "serverlessFeeAmount": 1.25, + "storageStandardAmount": 0, + "storageHighPerformanceAmount": 2.5, + "endpointAmount": 3.21, + "clusterGpuAmount": 2.5, + "clusterDiskAmount": 0.3, + "clusterNetworkingAmount": 0.24 + } + ], + "metadata": { + "query": { + "startTime": "2026-06-01T00:00:00Z", + "endTime": "2026-06-02T00:00:00Z", + "bucketSize": "day" + }, + "recordCount": 1, + "totals": { + "totalAmount": 42.34, + "podGpuAmount": 18.2, + "podCpuAmount": 0, + "podDiskAmount": 1.1, + "serverlessGpuAmount": 12.6, + "serverlessCpuAmount": 0, + "serverlessDiskAmount": 0.44, + "serverlessFeeAmount": 1.25, + "storageStandardAmount": 0, + "storageHighPerformanceAmount": 2.5, + "endpointAmount": 3.21, + "clusterGpuAmount": 2.5, + "clusterDiskAmount": 0.3, + "clusterNetworkingAmount": 0.24 + } + } + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/billing/pods": { + "get": { + "operationId": "listPodBilling", + "summary": "Get pod billing history", + "description": "Returns pod-only billing detail for the authenticated user, split into time buckets by startTime/endTime with bucketSize or by lastN recent buckets. Use podId to narrow the response to one GPU or CPU pod; without it, records are emitted per pod per bucket. Each record includes podId, GPU, CPU, disk, and total amounts, while metadata echoes the resolved query and totals across the pod records. Use listBilling when you need aggregate spend across every billable resource family.\n", + "tags": [ + "Billing" + ], + "parameters": [ + { + "$ref": "#/components/parameters/BillingStartTime" + }, + { + "$ref": "#/components/parameters/BillingEndTime" + }, + { + "$ref": "#/components/parameters/BillingBucketSize" + }, + { + "$ref": "#/components/parameters/BillingLastN" + }, + { + "name": "podId", + "in": "query", + "required": false, + "description": "Filter to a specific pod (GPU or CPU).", + "schema": { + "type": "string" + }, + "example": "pod_abc123" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListPodBillingResponse" + }, + "examples": { + "podBilling": { + "summary": "Successful response", + "value": { + "records": [ + { + "startTime": "2026-06-01T00:00:00Z", + "endTime": "2026-06-02T00:00:00Z", + "podId": "7h9k2m4n6p", + "totalAmount": 12.34, + "gpuAmount": 11.1, + "cpuAmount": 0, + "diskAmount": 1.24 + } + ], + "metadata": { + "query": { + "startTime": "2026-06-01T00:00:00Z", + "endTime": "2026-06-02T00:00:00Z", + "bucketSize": "day", + "podId": "7h9k2m4n6p" + }, + "recordCount": 1, + "totals": { + "totalAmount": 12.34, + "gpuAmount": 11.1, + "cpuAmount": 0, + "diskAmount": 1.24 + }, + "uniquePodCount": 1 + } + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/billing/serverless": { + "get": { + "operationId": "listServerlessBilling", + "summary": "Get serverless billing history", + "description": "Returns serverless endpoint billing detail for the authenticated user, split into time buckets by startTime/endTime with bucketSize or by lastN recent buckets. Use serverlessId to filter to one endpoint; without it, records are emitted per serverless endpoint per bucket. Each record reports endpoint-level GPU, CPU, disk, platform fee, and total amounts. This is distinct from pod billing, which covers standalone GPU and CPU pod costs rather than serverless endpoint workloads.\n", + "tags": [ + "Billing" + ], + "parameters": [ + { + "$ref": "#/components/parameters/BillingStartTime" + }, + { + "$ref": "#/components/parameters/BillingEndTime" + }, + { + "$ref": "#/components/parameters/BillingBucketSize" + }, + { + "$ref": "#/components/parameters/BillingLastN" + }, + { + "name": "serverlessId", + "in": "query", + "required": false, + "description": "Filter to a specific serverless endpoint.", + "schema": { + "type": "string" + }, + "example": "jpnw0v75y3qoql" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListServerlessBillingResponse" + }, + "examples": { + "serverlessBilling": { + "summary": "Successful response", + "value": { + "records": [ + { + "startTime": "2026-06-01T00:00:00Z", + "endTime": "2026-06-02T00:00:00Z", + "serverlessId": "4m7x2k9q", + "totalAmount": 8.9, + "gpuAmount": 7.5, + "cpuAmount": 0, + "diskAmount": 0.4, + "feeAmount": 1 + } + ], + "metadata": { + "query": { + "startTime": "2026-06-01T00:00:00Z", + "endTime": "2026-06-02T00:00:00Z", + "bucketSize": "day", + "serverlessId": "4m7x2k9q" + }, + "recordCount": 1, + "totals": { + "totalAmount": 8.9, + "gpuAmount": 7.5, + "cpuAmount": 0, + "diskAmount": 0.4, + "feeAmount": 1 + }, + "uniqueServerlessCount": 1 + } + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/billing/endpoints": { + "get": { + "operationId": "listEndpointBilling", + "summary": "Get public endpoint billing history", + "description": "Returns Runpod public endpoint billing history for the authenticated user, split into time buckets by startTime/endTime with bucketSize or by lastN recent buckets. Each record reports the endpoint total for one bucket, and metadata echoes the resolved query window, record count, and total endpoint amount across all returned records.\n", + "tags": [ + "Billing" + ], + "parameters": [ + { + "$ref": "#/components/parameters/BillingStartTime" + }, + { + "$ref": "#/components/parameters/BillingEndTime" + }, + { + "$ref": "#/components/parameters/BillingBucketSize" + }, + { + "$ref": "#/components/parameters/BillingLastN" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListEndpointBillingResponse" + }, + "examples": { + "endpointBilling": { + "summary": "Successful response", + "value": { + "records": [ + { + "startTime": "2026-06-01T00:00:00Z", + "endTime": "2026-06-02T00:00:00Z", + "totalAmount": 3.21 + } + ], + "metadata": { + "query": { + "startTime": "2026-06-01T00:00:00Z", + "endTime": "2026-06-02T00:00:00Z", + "bucketSize": "day" + }, + "recordCount": 1, + "totals": { + "totalAmount": 3.21 + } + } + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/billing/networkvolumes": { + "get": { + "operationId": "listNetworkVolumeBilling", + "summary": "Get network volume billing history", + "description": "Returns network volume billing history for the authenticated user, split into time buckets by startTime/endTime with bucketSize or by lastN recent buckets. Use networkVolumeId to filter to one volume; without it, records are emitted per volume per bucket. Each record includes standard storage, high-performance storage, and total amounts, while metadata reports the resolved query, distinct volume count, and totals across the returned records.\n", + "tags": [ + "Billing" + ], + "parameters": [ + { + "$ref": "#/components/parameters/BillingStartTime" + }, + { + "$ref": "#/components/parameters/BillingEndTime" + }, + { + "$ref": "#/components/parameters/BillingBucketSize" + }, + { + "$ref": "#/components/parameters/BillingLastN" + }, + { + "name": "networkVolumeId", + "in": "query", + "required": false, + "description": "Filter to a specific network volume.", + "schema": { + "type": "string" + }, + "example": "vol_abc123" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListNetworkVolumeBillingResponse" + }, + "examples": { + "networkVolumeBilling": { + "summary": "Successful response", + "value": { + "records": [ + { + "startTime": "2026-06-01T00:00:00Z", + "endTime": "2026-06-02T00:00:00Z", + "networkVolumeId": "2q9m7x4c", + "totalAmount": 5.79, + "standardAmount": 0, + "highPerformanceAmount": 5.79 + } + ], + "metadata": { + "query": { + "startTime": "2026-06-01T00:00:00Z", + "endTime": "2026-06-02T00:00:00Z", + "bucketSize": "day", + "networkVolumeId": "2q9m7x4c" + }, + "recordCount": 1, + "totals": { + "totalAmount": 5.79, + "standardAmount": 0, + "highPerformanceAmount": 5.79 + }, + "uniqueNetworkVolumeCount": 1 + } + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/v2/billing/clusters": { + "get": { + "operationId": "listClusterBilling", + "summary": "Get Instant Cluster billing history", + "description": "Returns Instant Cluster billing history for the authenticated user, split into time buckets by startTime/endTime with bucketSize or by lastN recent buckets. Use clusterId to filter to one cluster; without it, records are emitted per cluster per bucket. Each record includes GPU compute, disk, inter-node networking, and total amounts. Instant Clusters are GPU-only, so no CPU cost component is returned.\n", + "tags": [ + "Billing" + ], + "parameters": [ + { + "$ref": "#/components/parameters/BillingStartTime" + }, + { + "$ref": "#/components/parameters/BillingEndTime" + }, + { + "$ref": "#/components/parameters/BillingBucketSize" + }, + { + "$ref": "#/components/parameters/BillingLastN" + }, + { + "name": "clusterId", + "in": "query", + "required": false, + "description": "Filter to a specific Instant Cluster.", + "schema": { + "type": "string" + }, + "example": "cluster_abc123" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListClusterBillingResponse" + }, + "examples": { + "clusterBilling": { + "summary": "Successful response", + "value": { + "records": [ + { + "startTime": "2026-06-01T00:00:00Z", + "endTime": "2026-06-02T00:00:00Z", + "clusterId": "5c2n8m4q", + "totalAmount": 99, + "gpuAmount": 95, + "diskAmount": 3, + "networkingAmount": 1 + } + ], + "metadata": { + "query": { + "startTime": "2026-06-01T00:00:00Z", + "endTime": "2026-06-02T00:00:00Z", + "bucketSize": "day", + "clusterId": "5c2n8m4q" + }, + "recordCount": 1, + "totals": { + "totalAmount": 99, + "gpuAmount": 95, + "diskAmount": 3, + "networkingAmount": 1 + }, + "uniqueClusterCount": 1 + } + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, + "default": { + "description": "Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + } + } +} From b8843e15dbda31904de895e2c91c6115841f3bfb Mon Sep 17 00:00:00 2001 From: lgunreddi Date: Wed, 22 Jul 2026 10:46:09 -0400 Subject: [PATCH 33/41] Update overview.mdx --- api-reference/overview.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/api-reference/overview.mdx b/api-reference/overview.mdx index 9dfc944f..0dd3f022 100644 --- a/api-reference/overview.mdx +++ b/api-reference/overview.mdx @@ -3,10 +3,10 @@ title: "Overview" description: "Use the Runpod API to programmatically manage your compute resources. Review authentication, request formats, and response details for the Runpod API." --- -The Runpod REST API provides programmatic access to all Runpod compute resources. Integrate GPU infrastructure into your applications, workflows, and automation systems. +The Runpod REST API v1 provides programmatic access to all Runpod compute resources. Integrate GPU infrastructure into your applications, workflows, and automation systems. - **API v1 is deprecated and will be retired in the near future.** All new integrations should use [API v2](/api-reference-v2/overview) instead. + **REST API v1 is deprecated and will be retired in the near future.** All new integrations should use [REST API v2](/api-reference-v2/overview) instead. ## Available resources From 6cf35cf28fb4db4bb85895a1f02ba196b868509b Mon Sep 17 00:00:00 2001 From: lgunreddi Date: Wed, 22 Jul 2026 10:47:42 -0400 Subject: [PATCH 34/41] Update openapi.json --- api-reference-v2/openapi.json | 175 ++++++++++++++++++++++++++++++++++ 1 file changed, 175 insertions(+) diff --git a/api-reference-v2/openapi.json b/api-reference-v2/openapi.json index d7b026ff..cb08c0a1 100644 --- a/api-reference-v2/openapi.json +++ b/api-reference-v2/openapi.json @@ -184,6 +184,49 @@ } } } + }, + "TooManyRequestsError": { + "description": "The caller exceeded its per-user rate limit. The response identifies the window that was exceeded and how long to wait. The `RateLimit` and `RateLimit-Policy` headers (per the IETF ratelimit-headers draft) also accompany successful responses, so clients can track quota before a 429.\n", + "headers": { + "Retry-After": { + "description": "Seconds to wait before retrying, per the exceeded window.", + "schema": { + "type": "integer" + }, + "example": 12 + }, + "RateLimit": { + "description": "Live per-window state as a structured-field list — one member per window (`minute`, `hour`, `day`) with remaining count `r` and seconds-until-reset `t`.\n", + "schema": { + "type": "string" + }, + "example": "\"minute\";r=0;t=12, \"hour\";r=2800;t=1812, \"day\";r=49500;t=45012" + }, + "RateLimit-Policy": { + "description": "Static quota policy as a structured-field list — one member per window with quota `q` and window length `w` (seconds).\n", + "schema": { + "type": "string" + }, + "example": "\"minute\";q=60;w=60, \"hour\";q=3000;w=3600, \"day\";q=50000;w=86400" + } + }, + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + }, + "examples": { + "rateLimited": { + "summary": "Rate limit exceeded", + "value": { + "title": "Too Many Requests", + "status": 429, + "detail": "rate limit exceeded for the minute window" + } + } + } + } + } } }, "parameters": { @@ -3714,6 +3757,9 @@ "403": { "$ref": "#/components/responses/ForbiddenError" }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, "default": { "description": "Error", "content": { @@ -3826,6 +3872,9 @@ "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, "default": { "description": "Error", "content": { @@ -3928,6 +3977,9 @@ "404": { "$ref": "#/components/responses/NotFoundError" }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, "default": { "description": "Error", "content": { @@ -4040,6 +4092,9 @@ "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, "default": { "description": "Error", "content": { @@ -4072,6 +4127,9 @@ "404": { "$ref": "#/components/responses/NotFoundError" }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, "default": { "description": "Error", "content": { @@ -4166,6 +4224,9 @@ "404": { "$ref": "#/components/responses/NotFoundError" }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, "default": { "description": "Error", "content": { @@ -4304,6 +4365,9 @@ "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, "default": { "description": "Error", "content": { @@ -4394,6 +4458,9 @@ "403": { "$ref": "#/components/responses/ForbiddenError" }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, "default": { "description": "Error", "content": { @@ -4522,6 +4589,9 @@ "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, "default": { "description": "Error", "content": { @@ -4622,6 +4692,9 @@ "404": { "$ref": "#/components/responses/NotFoundError" }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, "default": { "description": "Error", "content": { @@ -4741,6 +4814,9 @@ "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, "default": { "description": "Error", "content": { @@ -4773,6 +4849,9 @@ "404": { "$ref": "#/components/responses/NotFoundError" }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, "default": { "description": "Error", "content": { @@ -4856,6 +4935,9 @@ "404": { "$ref": "#/components/responses/NotFoundError" }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, "default": { "description": "Error", "content": { @@ -4941,6 +5023,9 @@ "404": { "$ref": "#/components/responses/NotFoundError" }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, "default": { "description": "Error", "content": { @@ -5045,6 +5130,9 @@ "404": { "$ref": "#/components/responses/NotFoundError" }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, "default": { "description": "Error", "content": { @@ -5115,6 +5203,9 @@ "403": { "$ref": "#/components/responses/ForbiddenError" }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, "default": { "description": "Error", "content": { @@ -5220,6 +5311,9 @@ "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, "default": { "description": "Error", "content": { @@ -5300,6 +5394,9 @@ "404": { "$ref": "#/components/responses/NotFoundError" }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, "default": { "description": "Error", "content": { @@ -5391,6 +5488,9 @@ "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, "default": { "description": "Error", "content": { @@ -5433,6 +5533,9 @@ "404": { "$ref": "#/components/responses/NotFoundError" }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, "default": { "description": "Error", "content": { @@ -5487,6 +5590,9 @@ "403": { "$ref": "#/components/responses/ForbiddenError" }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, "default": { "description": "Error", "content": { @@ -5562,6 +5668,9 @@ "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, "default": { "description": "Error", "content": { @@ -5627,6 +5736,9 @@ "404": { "$ref": "#/components/responses/NotFoundError" }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, "default": { "description": "Error", "content": { @@ -5709,6 +5821,9 @@ "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, "default": { "description": "Error", "content": { @@ -5741,6 +5856,9 @@ "404": { "$ref": "#/components/responses/NotFoundError" }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, "default": { "description": "Error", "content": { @@ -5792,6 +5910,9 @@ "403": { "$ref": "#/components/responses/ForbiddenError" }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, "default": { "description": "Error", "content": { @@ -5863,6 +5984,9 @@ "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, "default": { "description": "Error", "content": { @@ -5924,6 +6048,9 @@ "404": { "$ref": "#/components/responses/NotFoundError" }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, "default": { "description": "Error", "content": { @@ -5966,6 +6093,9 @@ "404": { "$ref": "#/components/responses/NotFoundError" }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, "default": { "description": "Error", "content": { @@ -5997,6 +6127,9 @@ } } }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, "default": { "description": "Error", "content": { @@ -6036,6 +6169,9 @@ } } }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, "default": { "description": "Error", "content": { @@ -6081,6 +6217,9 @@ } } }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, "default": { "description": "Error", "content": { @@ -6170,6 +6309,9 @@ "403": { "$ref": "#/components/responses/ForbiddenError" }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, "default": { "description": "Error", "content": { @@ -6269,6 +6411,9 @@ "404": { "$ref": "#/components/responses/NotFoundError" }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, "default": { "description": "Error", "content": { @@ -6349,6 +6494,9 @@ "403": { "$ref": "#/components/responses/ForbiddenError" }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, "default": { "description": "Error", "content": { @@ -6439,6 +6587,9 @@ "404": { "$ref": "#/components/responses/NotFoundError" }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, "default": { "description": "Error", "content": { @@ -6597,6 +6748,9 @@ "403": { "$ref": "#/components/responses/ForbiddenError" }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, "default": { "description": "Error", "content": { @@ -6701,6 +6855,9 @@ "404": { "$ref": "#/components/responses/NotFoundError" }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, "default": { "description": "Error", "content": { @@ -6804,6 +6961,9 @@ "403": { "$ref": "#/components/responses/ForbiddenError" }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, "default": { "description": "Error", "content": { @@ -6900,6 +7060,9 @@ "403": { "$ref": "#/components/responses/ForbiddenError" }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, "default": { "description": "Error", "content": { @@ -6998,6 +7161,9 @@ "403": { "$ref": "#/components/responses/ForbiddenError" }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, "default": { "description": "Error", "content": { @@ -7075,6 +7241,9 @@ "403": { "$ref": "#/components/responses/ForbiddenError" }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, "default": { "description": "Error", "content": { @@ -7169,6 +7338,9 @@ "403": { "$ref": "#/components/responses/ForbiddenError" }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, "default": { "description": "Error", "content": { @@ -7265,6 +7437,9 @@ "403": { "$ref": "#/components/responses/ForbiddenError" }, + "429": { + "$ref": "#/components/responses/TooManyRequestsError" + }, "default": { "description": "Error", "content": { From 44aeee5de791e850eebeb0b03eccd2613dad7b91 Mon Sep 17 00:00:00 2001 From: lgunreddi Date: Wed, 22 Jul 2026 10:50:00 -0400 Subject: [PATCH 35/41] Update overview.mdx --- api-reference-v2/overview.mdx | 7512 +-------------------------------- 1 file changed, 55 insertions(+), 7457 deletions(-) diff --git a/api-reference-v2/overview.mdx b/api-reference-v2/overview.mdx index cb08c0a1..0db77954 100644 --- a/api-reference-v2/overview.mdx +++ b/api-reference-v2/overview.mdx @@ -1,7457 +1,55 @@ -{ - "openapi": "3.1.0", - "info": { - "title": "Runpod REST API", - "version": "2.0.0", - "description": "Runpod public REST API — v2" - }, - "servers": [ - { - "url": "https://api.runpod.io", - "description": "Runpod API v2 production server" - } - ], - "security": [ - { - "bearerAuth": [] - } - ], - "tags": [ - { - "name": "Pods", - "description": "GPU and CPU pod lifecycle, configuration, actions, and log streaming." - }, - { - "name": "Serverless", - "description": "Serverless endpoint lifecycle, worker visibility, releases, and worker log streaming." - }, - { - "name": "Templates", - "description": "Reusable pod and endpoint configuration templates." - }, - { - "name": "Network Volumes", - "description": "Persistent network storage volumes for workloads." - }, - { - "name": "Registries", - "description": "Container registry credentials used to pull private images." - }, - { - "name": "Catalog", - "description": "Available GPU, CPU, and data center catalog metadata." - }, - { - "name": "Billing", - "description": "Billing history and usage cost records across resource types." - } - ], - "components": { - "securitySchemes": { - "bearerAuth": { - "type": "http", - "scheme": "bearer", - "bearerFormat": "Runpod API Key", - "description": "Runpod API key authentication. Generate an API key in the Runpod console and send it in the `Authorization` header as `Bearer `. Keys are scoped to the permissions granted when created; requests may return `403` when a valid key lacks access to the requested resource or action.\n" - } - }, - "responses": { - "UnauthorizedError": { - "description": "Authentication failed because the bearer token is missing, malformed, expired, or invalid.", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "missingBearerToken": { - "summary": "Missing bearer token", - "value": { - "title": "Unauthorized", - "status": 401, - "detail": "missing bearer token" - } - } - } - } - } - }, - "ForbiddenError": { - "description": "The bearer token is valid, but it does not grant access to the requested resource or action.", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "insufficientAccess": { - "summary": "Insufficient access", - "value": { - "title": "Forbidden", - "status": 403, - "detail": "access denied" - } - } - } - } - } - }, - "BadRequestError": { - "description": "The request could not be processed because it is malformed or conflicts with request rules.", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "badRequest": { - "summary": "Bad request", - "value": { - "title": "Bad Request", - "status": 400, - "detail": "request could not be processed" - } - } - } - } - } - }, - "NotFoundError": { - "description": "The requested resource was not found or is not accessible to the caller.", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "notFound": { - "summary": "Resource not found", - "value": { - "title": "Not Found", - "status": 404, - "detail": "resource not found" - } - } - } - } - } - }, - "UnprocessableEntityError": { - "description": "The request body or parameters were syntactically valid but failed validation.", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "validationFailed": { - "summary": "Validation failed", - "value": { - "title": "Unprocessable Entity", - "status": 422, - "detail": "Request validation failed." - } - } - } - } - } - }, - "MethodNotAllowedError": { - "description": "The request method is not supported for the target path.", - "headers": { - "Allow": { - "description": "Comma-separated methods supported by the target path.", - "schema": { - "type": "string" - }, - "example": "GET, POST" - } - }, - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "methodNotAllowed": { - "summary": "Method not allowed", - "value": { - "title": "Method Not Allowed", - "status": 405, - "detail": "The requested method is not allowed for this path." - } - } - } - } - } - }, - "TooManyRequestsError": { - "description": "The caller exceeded its per-user rate limit. The response identifies the window that was exceeded and how long to wait. The `RateLimit` and `RateLimit-Policy` headers (per the IETF ratelimit-headers draft) also accompany successful responses, so clients can track quota before a 429.\n", - "headers": { - "Retry-After": { - "description": "Seconds to wait before retrying, per the exceeded window.", - "schema": { - "type": "integer" - }, - "example": 12 - }, - "RateLimit": { - "description": "Live per-window state as a structured-field list — one member per window (`minute`, `hour`, `day`) with remaining count `r` and seconds-until-reset `t`.\n", - "schema": { - "type": "string" - }, - "example": "\"minute\";r=0;t=12, \"hour\";r=2800;t=1812, \"day\";r=49500;t=45012" - }, - "RateLimit-Policy": { - "description": "Static quota policy as a structured-field list — one member per window with quota `q` and window length `w` (seconds).\n", - "schema": { - "type": "string" - }, - "example": "\"minute\";q=60;w=60, \"hour\";q=3000;w=3600, \"day\";q=50000;w=86400" - } - }, - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "rateLimited": { - "summary": "Rate limit exceeded", - "value": { - "title": "Too Many Requests", - "status": 429, - "detail": "rate limit exceeded for the minute window" - } - } - } - } - } - } - }, - "parameters": { - "BillingStartTime": { - "name": "startTime", - "in": "query", - "required": false, - "description": "Start of the billing period (RFC 3339). Defaults to 30 days ago. Snapped down to the start of its bucketSize bucket so the window aligns with the returned records; provide a boundary-aligned value (e.g. midnight for bucketSize=day) to avoid widening.\n", - "schema": { - "type": "string", - "format": "date-time" - }, - "example": "2026-05-01T00:00:00Z" - }, - "BillingEndTime": { - "name": "endTime", - "in": "query", - "required": false, - "description": "End of the billing period (RFC 3339), exclusive. Defaults to now. Snapped up to the end of the bucketSize bucket it lands in (unless already on a boundary) so the window aligns with the returned records.\n", - "schema": { - "type": "string", - "format": "date-time" - }, - "example": "2026-06-01T00:00:00Z" - }, - "BillingBucketSize": { - "name": "bucketSize", - "in": "query", - "required": false, - "description": "Length of each billing time bucket. Defaults to day.", - "schema": { - "$ref": "#/components/schemas/BillingBucketSize" - } - }, - "BillingLastN": { - "name": "lastN", - "in": "query", - "required": false, - "description": "Return the last N buckets of bucketSize, ending with the current (in-progress) bucket — e.g. lastN=100 with bucketSize=day is \"last 100 days\". The resolved window is aligned to bucket boundaries: startTime is the start of the earliest bucket (e.g. midnight of the earliest day) and endTime is the end of the current bucket. Mutually exclusive with startTime/endTime; provide one or the other, not both.\n", - "schema": { - "type": "integer", - "minimum": 1 - }, - "example": 30 - }, - "CatalogIncludeParam": { - "name": "include", - "in": "query", - "required": false, - "description": "Comma-separated optional expansions. Supported value today: AVAILABILITY. This may expand with more include values in the future.", - "style": "form", - "explode": false, - "schema": { - "type": "array", - "maxItems": 1, - "items": { - "$ref": "#/components/schemas/CatalogInclude" - } - }, - "example": [ - "AVAILABILITY" - ] - }, - "GpuProductFilter": { - "name": "product", - "in": "query", - "required": false, - "description": "Comma-separated availability product contexts. Supported values: POD, CLUSTER, SERVERLESS. Valid only with include=AVAILABILITY. Upstream default when omitted: POD.", - "style": "form", - "explode": false, - "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Product" - } - }, - "example": [ - "POD", - "SERVERLESS" - ] - }, - "GpuCountFilter": { - "name": "count", - "in": "query", - "required": false, - "description": "GPU count for availability and lowest-price calculations. Valid only with include=AVAILABILITY. Defaults to 1.", - "schema": { - "type": "integer", - "minimum": 1, - "default": 1 - }, - "example": 2 - }, - "GpuCloudFilter": { - "name": "cloud", - "in": "query", - "required": false, - "description": "Cloud type for availability and lowest-price calculations. Valid only with include=AVAILABILITY. Supported values: SECURE, COMMUNITY. Upstream default when omitted: SECURE.", - "schema": { - "$ref": "#/components/schemas/GpuCloudFilter" - } - }, - "MinCudaVersionFilter": { - "name": "minCudaVersion", - "in": "query", - "required": false, - "description": "Minimum CUDA version for availability and lowest-price calculations. Valid only with include=AVAILABILITY. Format: integer major or major.minor, e.g. 12 or 12.1.", - "schema": { - "type": "string" - }, - "example": "12.1" - }, - "CpuProductFilter": { - "name": "product", - "in": "query", - "required": false, - "description": "Comma-separated availability product context. Valid only with include=AVAILABILITY. Supported values for CPUs: POD, SERVERLESS. Defaults to POD when omitted.", - "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/CpuProduct" - }, - "example": [ - "POD", - "SERVERLESS" - ] - } - }, - "CpuVCPUCountFilter": { - "name": "vcpuCount", - "in": "query", - "required": false, - "description": "Availability vCPU count. Valid only with include=AVAILABILITY. Must be a power of two.", - "schema": { - "type": "integer", - "minimum": 2 - }, - "example": 4 - }, - "LogSourceParam": { - "name": "source", - "in": "query", - "required": false, - "description": "Log source to stream. Omit to include both container and system logs.", - "schema": { - "$ref": "#/components/schemas/LogSource" - } - }, - "LogTail": { - "name": "tail", - "in": "query", - "required": false, - "description": "Number of historical lines to backfill before streaming. Defaults to\n100 when omitted; set `0` to stream live with no backfill. Maximum 5000.\nIgnored when `since` or `Last-Event-ID` is provided — the resume cursor\ndrives the backfill instead.\n", - "schema": { - "type": "integer", - "minimum": 0, - "maximum": 5000, - "default": 100 - } - }, - "LogSince": { - "name": "since", - "in": "query", - "required": false, - "description": "RFC3339 timestamp to resume from. Ignored when `Last-Event-ID` is\nprovided. When set, the stream resumes from this point and `tail` is\nignored.\n", - "schema": { - "type": "string", - "format": "date-time" - } - }, - "LogLastEventID": { - "name": "Last-Event-ID", - "in": "header", - "required": false, - "description": "SSE reconnect cursor — a timestamp emitted by this endpoint. Takes\nprecedence over `since` and `tail`: when present, the stream resumes\nfrom this point. Sent automatically by EventSource on reconnect.\n", - "schema": { - "type": "string", - "format": "date-time" - } - } - }, - "schemas": { - "ContainerConfig": { - "type": "object", - "description": "Reusable container configuration shared across templates, pods, and serverless endpoints. Adding a field here automatically propagates to all three resources.\n", - "properties": { - "image": { - "type": "string", - "description": "Docker image reference", - "examples": [ - "runpod/pytorch:2.8.0-py3.11-cuda12.8.1" - ] - }, - "args": { - "type": "string", - "description": "Arguments passed to the container entrypoint", - "examples": [ - "" - ] - }, - "disk": { - "type": "integer", - "minimum": 1, - "description": "Container disk in GB (ephemeral, wiped on restart)", - "examples": [ - 50 - ] - }, - "ports": { - "type": "array", - "description": "Exposed ports, formatted as port/protocol", - "items": { - "type": "string" - }, - "examples": [ - [ - "8888/http", - "22/tcp" - ] - ] - }, - "env": { - "type": "object", - "additionalProperties": { - "type": "string" - }, - "description": "Environment variables as key-value pairs", - "examples": [ - { - "JUPYTER_PASSWORD": "hunter2" - } - ] - }, - "registry": { - "type": [ - "string", - "null" - ], - "description": "Container registry credential ID (for private images)", - "examples": [ - null - ] - } - } - }, - "Mounts": { - "type": "object", - "additionalProperties": false, - "description": "Storage mounts attached to a pod. At-most-one of `persistent` or\n`network` may be set today (mutually exclusive, enforced at the\nhandler with 400 if both are present). The `network` field is an\narray for forward compatibility with eventual multi-network-volume\nsupport, but `maxItems` is 1 today.\n\nPATCH semantics:\n- Omitting `mounts` or sending `{}` leaves the existing mount\n unchanged.\n- An explicit `network: []` is rejected with 400 (clearing mounts\n is not supported).\n- Mount kind is fixed at create — a PATCH that introduces a kind\n not present at create (persistent on a network pod, network on\n a persistent pod, or any mount on a previously-mountless pod)\n is rejected with 400.\n- The `volumeId` of a network mount is immutable; a PATCH that\n names a different `volumeId` is rejected with 400.\n- Partial mounts are not supported — every mount entry must\n include the full schema (`size` + `path` for persistent,\n `volumeId` + `path` for network). Missing required fields → 422.\n", - "properties": { - "persistent": { - "$ref": "#/components/schemas/PersistentMount" - }, - "network": { - "type": "array", - "maxItems": 1, - "items": { - "$ref": "#/components/schemas/NetworkMount" - } - } - } - }, - "TemplateMounts": { - "type": "object", - "additionalProperties": false, - "description": "Storage mounts attached to a template. Templates support only a\nsingle persistent mount today; any `network` property is rejected\nwith 422 by the schema validator.\n\nPATCH semantics: omitting `mounts` or sending `{}` leaves the\nexisting mount unchanged.\n", - "properties": { - "persistent": { - "$ref": "#/components/schemas/PersistentMount" - } - } - }, - "PersistentMount": { - "type": "object", - "required": [ - "size", - "path" - ], - "additionalProperties": false, - "description": "Host-local persistent storage. Pinned to the pod's host machine — data\ndoes not survive a host failure. Disallowed on CPU pods. Mutually\nexclusive with NetworkMount. Deprecated: prefer NetworkMount for any\ndata you cannot recreate.\n", - "properties": { - "size": { - "type": "integer", - "minimum": 10, - "description": "Host-local persistent storage in GB. Upstream enforces a 10 GB floor.", - "examples": [ - 20 - ] - }, - "path": { - "type": "string", - "description": "Mount path inside the container. May be changed via PATCH.", - "examples": [ - "/workspace" - ] - } - } - }, - "NetworkMount": { - "type": "object", - "required": [ - "volumeId", - "path" - ], - "additionalProperties": false, - "description": "Reference to a NetworkVolume. Custom paths are honored at runtime on\nboth GPU and CPU pods. The underlying `volumeId` is immutable\npost-create; the mount `path` may be changed via PATCH.\n", - "properties": { - "volumeId": { - "type": "string", - "description": "ID of an existing NetworkVolume in the same data center as the pod.", - "examples": [ - "vol_xyz" - ] - }, - "path": { - "type": "string", - "description": "Mount path inside the container. No default — must be specified explicitly.", - "examples": [ - "/runpod-volume" - ] - } - } - }, - "GpuConfig": { - "type": "object", - "required": [ - "id" - ], - "properties": { - "id": { - "type": "string", - "description": "GPU type identifier", - "examples": [ - "NVIDIA GeForce RTX 4090" - ] - }, - "count": { - "type": "integer", - "minimum": 1, - "default": 1, - "description": "Number of GPUs", - "examples": [ - 1 - ] - } - } - }, - "BaseCpuConfig": { - "type": "object", - "required": [ - "id", - "vcpuCount" - ], - "properties": { - "id": { - "type": "string", - "description": "CPU flavor identifier, as returned by GET /v2/catalog/cpus.", - "examples": [ - "cpu5c" - ], - "minLength": 1 - }, - "vcpuCount": { - "type": "integer", - "minimum": 2, - "description": "Number of vCPUs. Must be valid for the selected CPU flavor and must be a power of two.", - "examples": [ - 4 - ] - } - } - }, - "CreateCpuConfig": { - "allOf": [ - { - "$ref": "#/components/schemas/BaseCpuConfig" - } - ], - "unevaluatedProperties": false - }, - "CpuConfig": { - "allOf": [ - { - "$ref": "#/components/schemas/BaseCpuConfig" - }, - { - "type": "object", - "required": [ - "memory" - ], - "properties": { - "memory": { - "type": "integer", - "minimum": 1, - "description": "Memory allocated to the pod in GB.", - "examples": [ - 16 - ] - } - } - } - ] - }, - "ScalerType": { - "type": "string", - "description": "Autoscaling strategy.\n- `QUEUE_DELAY` — scale on seconds a request waits in queue\n- `REQUEST_COUNT` — scale on in-flight request count\n", - "enum": [ - "QUEUE_DELAY", - "REQUEST_COUNT" - ] - }, - "FlashBoot": { - "type": "string", - "description": "FlashBoot cold-start acceleration mode.\n- `OFF` — disabled\n- `FLASHBOOT` — enabled\n- `PRIORITY_FLASHBOOT` — enabled with priority capacity\n", - "enum": [ - "OFF", - "FLASHBOOT", - "PRIORITY_FLASHBOOT" - ] - }, - "EndpointType": { - "type": "string", - "description": "Request-routing semantics for a modern serverless endpoint.\n- `QUEUE_BASED` — submit asynchronous or synchronous jobs through the managed queue.\n- `LOAD_BALANCING` — send requests directly to worker-defined HTTP paths.\n", - "x-enum-varnames": [ - "EndpointTypeQueueBased", - "EndpointTypeLoadBalancing" - ], - "enum": [ - "QUEUE_BASED", - "LOAD_BALANCING" - ] - }, - "QueueBasedRequestUrls": { - "type": "object", - "additionalProperties": false, - "required": [ - "run", - "runSync" - ], - "properties": { - "run": { - "type": "string", - "format": "uri", - "description": "URL for asynchronously submitting a queued job.", - "examples": [ - "https://api.runpod.ai/v2/4m7x2k9q/run" - ] - }, - "runSync": { - "type": "string", - "format": "uri", - "description": "URL for synchronously submitting a queued job.", - "examples": [ - "https://api.runpod.ai/v2/4m7x2k9q/runsync" - ] - } - } - }, - "LoadBalancingRequestUrls": { - "type": "object", - "additionalProperties": false, - "required": [ - "base" - ], - "properties": { - "base": { - "type": "string", - "format": "uri", - "description": "Base URL for worker-defined HTTP and WebSocket paths.", - "examples": [ - "https://4m7x2k9q.api.runpod.ai" - ] - } - } - }, - "EndpointRequestUrls": { - "description": "Request submission URLs appropriate to the endpoint's top-level `type`.\nQueue-based endpoints provide `run` and `runSync`; load-balancing\nendpoints provide `base` because their paths are worker-defined.\n", - "oneOf": [ - { - "$ref": "#/components/schemas/QueueBasedRequestUrls" - }, - { - "$ref": "#/components/schemas/LoadBalancingRequestUrls" - } - ] - }, - "EndpointGpuConfig": { - "type": "object", - "required": [ - "pools" - ], - "properties": { - "pools": { - "type": "array", - "minItems": 1, - "description": "Serverless GPU pool IDs (as returned by `GET /v2/catalog/gpus` in\n`pool`). Workers are placed on whichever listed pool has capacity.\n", - "items": { - "type": "string" - }, - "examples": [ - [ - "ADA_24" - ] - ] - }, - "count": { - "type": "integer", - "minimum": 1, - "default": 1, - "description": "GPUs per worker", - "examples": [ - 1 - ] - } - } - }, - "Endpoint": { - "allOf": [ - { - "$ref": "#/components/schemas/ContainerConfig" - }, - { - "type": "object", - "required": [ - "id", - "name", - "workers", - "scaling", - "dataCenterIds", - "networkVolumes", - "timeout", - "flashboot", - "createdAt" - ], - "properties": { - "id": { - "type": "string", - "examples": [ - "ep_abc123" - ] - }, - "name": { - "type": "string", - "examples": [ - "my-inference" - ] - }, - "type": { - "$ref": "#/components/schemas/EndpointType" - }, - "requestUrls": { - "$ref": "#/components/schemas/EndpointRequestUrls" - }, - "gpu": { - "anyOf": [ - { - "$ref": "#/components/schemas/EndpointGpuConfig" - }, - { - "type": "null" - } - ] - }, - "cpu": { - "description": "Read-only. Present for CPU serverless endpoints; CPU create/update is not yet supported.", - "anyOf": [ - { - "$ref": "#/components/schemas/CpuConfig" - }, - { - "type": "null" - } - ] - }, - "workers": { - "type": "object", - "required": [ - "min", - "max" - ], - "properties": { - "min": { - "type": "integer", - "minimum": 0, - "examples": [ - 0 - ] - }, - "max": { - "type": "integer", - "minimum": 0, - "examples": [ - 5 - ] - } - } - }, - "scaling": { - "type": "object", - "required": [ - "type", - "value", - "idleTimeout" - ], - "properties": { - "type": { - "$ref": "#/components/schemas/ScalerType" - }, - "value": { - "type": "number", - "format": "float", - "minimum": 0.5, - "examples": [ - 4 - ] - }, - "idleTimeout": { - "type": "integer", - "minimum": 0, - "description": "Seconds before idle workers scale down", - "examples": [ - 5 - ] - } - } - }, - "dataCenterIds": { - "type": "array", - "items": { - "type": "string" - }, - "examples": [ - [ - "US-TX-3" - ] - ] - }, - "networkVolumes": { - "type": "array", - "items": { - "type": "string" - }, - "examples": [ - [ - "vol_abc" - ] - ] - }, - "timeout": { - "type": "integer", - "description": "Per-request execution timeout in milliseconds", - "examples": [ - 300000 - ] - }, - "flashboot": { - "$ref": "#/components/schemas/FlashBoot" - }, - "createdAt": { - "type": "string", - "format": "date-time", - "examples": [ - "2026-03-13T20:00:00Z" - ] - } - } - } - ] - }, - "ListEndpointsResponse": { - "type": "object", - "required": [ - "endpoints" - ], - "properties": { - "endpoints": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Endpoint" - } - } - } - }, - "WorkerStatus": { - "type": "string", - "description": "Derived worker state, reconciled from the worker pod's lifecycle status\nand the live job-queue view.\n- `RUNNING` — actively processing a job\n- `IDLE` — ready and polling for jobs\n- `INITIALIZING` — starting up, not yet ready\n- `THROTTLED` — waiting on compute capacity\n- `UNHEALTHY` — failing health checks\n", - "x-enum-varnames": [ - "WorkerStatusRunning", - "WorkerStatusIdle", - "WorkerStatusInitializing", - "WorkerStatusThrottled", - "WorkerStatusUnhealthy" - ], - "enum": [ - "RUNNING", - "IDLE", - "INITIALIZING", - "THROTTLED", - "UNHEALTHY" - ] - }, - "Worker": { - "type": "object", - "required": [ - "id", - "status", - "gpuCount", - "isStale" - ], - "properties": { - "id": { - "type": "string", - "examples": [ - "worker_abc" - ] - }, - "status": { - "$ref": "#/components/schemas/WorkerStatus" - }, - "isStale": { - "type": "boolean", - "description": "True when the worker is running an older endpoint configuration than\nthe current one (e.g. mid rolling-update). This is the authoritative\nflag: it is derived from `version` vs the response's `endpointVersion`,\nexcept on legacy endpoints (`endpointVersion` 1) where it falls back\nto a container-image comparison.\n", - "examples": [ - false - ] - }, - "version": { - "type": [ - "integer", - "null" - ], - "description": "Endpoint configuration version this worker is running. Compare with\nthe response's `endpointVersion`. Null if unknown.\n", - "examples": [ - 4 - ] - }, - "gpuCount": { - "type": "integer", - "minimum": 0, - "description": "GPUs allocated to the worker.", - "examples": [ - 1 - ] - }, - "image": { - "type": [ - "string", - "null" - ], - "description": "Container image the worker is running.", - "examples": [ - "my-org/sdxl-worker:latest" - ] - }, - "uptimeSeconds": { - "type": [ - "integer", - "null" - ], - "minimum": 0, - "description": "Seconds the worker has been running. Null until the worker is placed and running.", - "examples": [ - 3600 - ] - }, - "gpuTypeId": { - "type": [ - "string", - "null" - ], - "description": "GPU type the worker is placed on. Null until the worker is placed.", - "examples": [ - "NVIDIA RTX 4090" - ] - }, - "dataCenterId": { - "type": [ - "string", - "null" - ], - "description": "Data center the worker is placed in. Null until the worker is placed.", - "examples": [ - "US-TX-3" - ] - }, - "startedAt": { - "type": [ - "string", - "null" - ], - "format": "date-time", - "description": "When the worker last started. Null if it has not started.", - "examples": [ - "2026-03-26T00:00:00Z" - ] - } - } - }, - "WorkerSummary": { - "type": "object", - "description": "Histogram of the returned workers by status. The per-status counts are a\nroll-up of the `workers` array, so `running + idle + initializing +\nthrottled + unhealthy == total == len(workers)`.\n", - "required": [ - "running", - "idle", - "initializing", - "throttled", - "unhealthy", - "total" - ], - "properties": { - "running": { - "type": "integer", - "minimum": 0, - "description": "Workers actively processing a job.", - "examples": [ - 2 - ] - }, - "idle": { - "type": "integer", - "minimum": 0, - "description": "Ready workers polling for jobs.", - "examples": [ - 1 - ] - }, - "initializing": { - "type": "integer", - "minimum": 0, - "description": "Workers starting up, not yet ready.", - "examples": [ - 0 - ] - }, - "throttled": { - "type": "integer", - "minimum": 0, - "description": "Workers waiting on compute capacity.", - "examples": [ - 0 - ] - }, - "unhealthy": { - "type": "integer", - "minimum": 0, - "description": "Workers failing health checks.", - "examples": [ - 0 - ] - }, - "total": { - "type": "integer", - "minimum": 0, - "description": "All workers currently allocated to the endpoint.", - "examples": [ - 3 - ] - } - } - }, - "ListEndpointWorkersResponse": { - "type": "object", - "required": [ - "workers", - "summary" - ], - "properties": { - "workers": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Worker" - } - }, - "summary": { - "$ref": "#/components/schemas/WorkerSummary" - }, - "endpointVersion": { - "type": [ - "integer", - "null" - ], - "description": "The endpoint's current configuration version. A worker whose\n`version` differs is running stale config (see `worker.isStale`).\nNull if unknown.\n", - "examples": [ - 4 - ] - } - } - }, - "ReleaseSource": { - "type": "string", - "description": "What produced the release.\n- `GIT_BUILD` — a completed GitHub build (see `buildId`)\n- `MANUAL` — a manual configuration change\n", - "x-enum-varnames": [ - "ReleaseSourceGitBuild", - "ReleaseSourceManual" - ], - "enum": [ - "GIT_BUILD", - "MANUAL" - ] - }, - "ReleaseDiffEntry": { - "type": "object", - "required": [ - "field", - "old", - "new" - ], - "properties": { - "field": { - "type": "string", - "description": "The changed configuration field. Top-level (e.g. `gpuCount`,\n`locations`) or template-scoped (e.g. `template.imageName`,\n`template.env`).\n", - "examples": [ - "template.imageName" - ] - }, - "old": { - "description": "Previous value, as raw JSON. Null when the field was added." - }, - "new": { - "description": "New value, as raw JSON. Null when the field was removed." - } - } - }, - "Release": { - "type": "object", - "required": [ - "id", - "source", - "createdAt", - "workerCount", - "diff" - ], - "properties": { - "id": { - "type": "string", - "examples": [ - "rel_abc123" - ] - }, - "version": { - "type": [ - "integer", - "null" - ], - "description": "The endpoint configuration version this release produced.", - "examples": [ - 4 - ] - }, - "source": { - "$ref": "#/components/schemas/ReleaseSource" - }, - "buildId": { - "type": [ - "string", - "null" - ], - "description": "The GitHub build that produced this release. Set when `source` is\n`GIT_BUILD`; null for `MANUAL` releases. Fetch build detail/logs via\n`/v2/serverless/{id}/builds/{buildId}`.\n", - "examples": [ - "build_abc123" - ] - }, - "createdByUserId": { - "type": [ - "string", - "null" - ], - "description": "ID of the user who created the release." - }, - "workerCount": { - "type": "integer", - "minimum": 0, - "description": "Workers currently running this release's version.", - "examples": [ - 2 - ] - }, - "createdAt": { - "type": "string", - "format": "date-time", - "examples": [ - "2026-03-13T20:00:00Z" - ] - }, - "diff": { - "type": "array", - "description": "Configuration fields that changed in this release.", - "items": { - "$ref": "#/components/schemas/ReleaseDiffEntry" - } - } - } - }, - "RolloutSummary": { - "type": "object", - "required": [ - "inProgress", - "workersOnLatest", - "workersTotal", - "percentOnLatest" - ], - "properties": { - "inProgress": { - "type": "boolean", - "description": "True while any worker is still running an older version.", - "examples": [ - true - ] - }, - "workersOnLatest": { - "type": "integer", - "minimum": 0, - "description": "Workers running the endpoint's current version.", - "examples": [ - 2 - ] - }, - "workersTotal": { - "type": "integer", - "minimum": 0, - "description": "All workers currently allocated to the endpoint.", - "examples": [ - 3 - ] - }, - "percentOnLatest": { - "type": "integer", - "minimum": 0, - "maximum": 100, - "description": "Percentage of workers on the current version (0 when there are no workers).", - "examples": [ - 67 - ] - } - } - }, - "ListEndpointReleasesResponse": { - "type": "object", - "required": [ - "rollout", - "releases" - ], - "properties": { - "endpointVersion": { - "type": [ - "integer", - "null" - ], - "description": "The endpoint's current configuration version. Null if unknown.", - "examples": [ - 4 - ] - }, - "rollout": { - "$ref": "#/components/schemas/RolloutSummary" - }, - "releases": { - "type": "array", - "description": "Release history, newest first.", - "items": { - "$ref": "#/components/schemas/Release" - } - } - } - }, - "CreateEndpointRequest": { - "allOf": [ - { - "$ref": "#/components/schemas/ContainerConfig" - }, - { - "type": "object", - "required": [ - "name", - "image", - "gpu" - ], - "properties": { - "name": { - "type": "string", - "minLength": 1, - "examples": [ - "my-inference" - ] - }, - "gpu": { - "allOf": [ - { - "$ref": "#/components/schemas/EndpointGpuConfig" - } - ], - "unevaluatedProperties": false - }, - "workers": { - "type": "object", - "additionalProperties": false, - "properties": { - "min": { - "type": "integer", - "minimum": 0, - "default": 0 - }, - "max": { - "type": "integer", - "minimum": 0, - "default": 3 - } - } - }, - "scaling": { - "type": "object", - "additionalProperties": false, - "properties": { - "type": { - "$ref": "#/components/schemas/ScalerType" - }, - "value": { - "type": "number", - "format": "float", - "minimum": 0.5, - "default": 4 - }, - "idleTimeout": { - "type": "integer", - "minimum": 0, - "default": 5 - } - } - }, - "dataCenterIds": { - "type": "array", - "items": { - "type": "string" - }, - "description": "Preferred data centers for placement. Omit or pass an empty array to let the scheduler choose." - }, - "networkVolumes": { - "type": "array", - "items": { - "type": "string" - } - }, - "timeout": { - "type": "integer", - "default": 300000 - }, - "flashboot": { - "allOf": [ - { - "$ref": "#/components/schemas/FlashBoot" - } - ], - "default": "OFF" - } - } - } - ], - "unevaluatedProperties": false - }, - "UpdateEndpointRequest": { - "allOf": [ - { - "$ref": "#/components/schemas/ContainerConfig" - }, - { - "type": "object", - "description": "Only provided fields are changed.", - "properties": { - "name": { - "type": "string", - "minLength": 1 - }, - "gpu": { - "allOf": [ - { - "$ref": "#/components/schemas/EndpointGpuConfig" - } - ], - "unevaluatedProperties": false - }, - "workers": { - "type": "object", - "additionalProperties": false, - "properties": { - "min": { - "type": "integer", - "minimum": 0 - }, - "max": { - "type": "integer", - "minimum": 0 - } - } - }, - "scaling": { - "type": "object", - "additionalProperties": false, - "properties": { - "type": { - "$ref": "#/components/schemas/ScalerType" - }, - "value": { - "type": "number", - "format": "float", - "minimum": 0.5 - }, - "idleTimeout": { - "type": "integer", - "minimum": 0 - } - } - }, - "dataCenterIds": { - "type": "array", - "items": { - "type": "string" - }, - "description": "Preferred data centers for placement. Omit or pass an empty array to let the scheduler choose." - }, - "networkVolumes": { - "type": "array", - "items": { - "type": "string" - } - }, - "timeout": { - "type": "integer" - }, - "flashboot": { - "$ref": "#/components/schemas/FlashBoot" - } - } - } - ], - "unevaluatedProperties": false - }, - "Utilization": { - "type": "object", - "description": "Single-value utilization percentage (0–100). Shared by `cpu` and `memory`.", - "properties": { - "util": { - "type": "integer", - "examples": [ - 45 - ] - } - } - }, - "PodGpuUtilization": { - "type": "object", - "description": "Per-GPU utilization metrics.", - "properties": { - "util": { - "type": "integer", - "examples": [ - 94 - ] - }, - "memoryUtil": { - "type": "integer", - "examples": [ - 78 - ] - } - } - }, - "PodRuntimePort": { - "type": "object", - "description": "Live port mapping for a running pod.", - "properties": { - "private": { - "type": "integer", - "examples": [ - 8888 - ] - }, - "public": { - "type": [ - "integer", - "null" - ], - "examples": [ - 43210 - ] - }, - "type": { - "type": "string", - "examples": [ - "http" - ] - }, - "ip": { - "type": [ - "string", - "null" - ], - "examples": [ - "45.23.12.1" - ] - } - } - }, - "PodRuntime": { - "type": "object", - "description": "Live utilization metrics for a running pod.", - "properties": { - "uptime": { - "type": "integer", - "description": "Seconds since the container started", - "examples": [ - 3600 - ] - }, - "gpus": { - "type": "array", - "items": { - "$ref": "#/components/schemas/PodGpuUtilization" - } - }, - "cpu": { - "$ref": "#/components/schemas/Utilization" - }, - "memory": { - "$ref": "#/components/schemas/Utilization" - }, - "ports": { - "type": "array", - "items": { - "$ref": "#/components/schemas/PodRuntimePort" - } - } - } - }, - "PodStatus": { - "type": "string", - "description": "Lifecycle status of a pod.\n- `PROVISIONING` — pod is being allocated\n- `STARTING` — container is starting\n- `RUNNING` — container is healthy\n- `EXITED` — container exited (stopped)\n- `ERROR` — container is in an unrecoverable error state\n- `TERMINATED` — pod has been permanently deleted\n", - "enum": [ - "PROVISIONING", - "STARTING", - "RUNNING", - "EXITED", - "ERROR", - "TERMINATED" - ] - }, - "PodAction": { - "type": "string", - "description": "State transition to trigger on a pod.", - "enum": [ - "start", - "stop", - "restart", - "terminate" - ] - }, - "LogSource": { - "type": "string", - "description": "Log source to include in a log stream.\n- `container` — container stdout/stderr log stream\n- `system` — host lifecycle/userlogs stream\n", - "x-enum-varnames": [ - "LogSourceContainer", - "LogSourceSystem" - ], - "enum": [ - "container", - "system" - ] - }, - "Cloud": { - "type": "string", - "description": "Cloud tier.\n- `SECURE` — Runpod-owned datacenter hardware\n- `COMMUNITY` — community-hosted hardware\n", - "enum": [ - "SECURE", - "COMMUNITY" - ] - }, - "TemplateCategory": { - "type": "string", - "description": "Controls how the template is grouped and filtered in the Runpod console.\nIt does not affect hardware selection, scheduling, or billing.\n- `CPU` — CPU-only workloads\n- `NVIDIA` — NVIDIA GPU workloads\n- `AMD` — AMD GPU workloads\n", - "enum": [ - "CPU", - "NVIDIA", - "AMD" - ] - }, - "PodGlobalNetworking": { - "type": "object", - "required": [ - "enabled" - ], - "properties": { - "enabled": { - "type": "boolean", - "description": "Whether global networking is enabled, giving the pod a private IP reachable across data centers. Derived from whether the pod has an assigned global-network address.", - "examples": [ - true - ] - }, - "ip": { - "type": "string", - "description": "The pod's assigned global-networking IP. Present only when enabled.", - "examples": [ - "10.65.1.42" - ] - }, - "internalDns": { - "type": "string", - "description": "Internal DNS name (`.runpod.internal`), reachable from other globally-networked pods in the same account. Present only when enabled.", - "examples": [ - "gfj8b292vyg08g.runpod.internal" - ] - } - } - }, - "Pod": { - "allOf": [ - { - "$ref": "#/components/schemas/ContainerConfig" - }, - { - "type": "object", - "required": [ - "id", - "name", - "status", - "actions", - "image", - "args", - "disk", - "mounts", - "ports", - "env", - "registry", - "cloud", - "dataCenterId", - "template", - "cost", - "locked", - "runtime", - "createdAt", - "startedAt", - "globalNetworking" - ], - "properties": { - "id": { - "type": "string", - "examples": [ - "pod_abc123" - ] - }, - "name": { - "type": "string", - "examples": [ - "my-training-pod" - ] - }, - "status": { - "$ref": "#/components/schemas/PodStatus" - }, - "actions": { - "type": "array", - "description": "Valid state transitions for the current status.", - "items": { - "$ref": "#/components/schemas/PodAction" - } - }, - "mounts": { - "$ref": "#/components/schemas/Mounts" - }, - "gpu": { - "description": "Present for GPU pods; omitted from CPU pods.", - "allOf": [ - { - "$ref": "#/components/schemas/GpuConfig" - } - ] - }, - "cpu": { - "description": "Present for CPU pods; omitted from GPU pods.", - "allOf": [ - { - "$ref": "#/components/schemas/CpuConfig" - } - ] - }, - "cloud": { - "$ref": "#/components/schemas/Cloud" - }, - "dataCenterId": { - "type": [ - "string", - "null" - ], - "description": "Data center where the pod is running (assigned by scheduler)", - "examples": [ - "US-TX-3" - ] - }, - "template": { - "type": [ - "string", - "null" - ], - "description": "ID of the template this pod was created from", - "examples": [ - null - ] - }, - "cost": { - "type": "number", - "format": "float", - "description": "Current cost in USD per hour (0.0 when EXITED or TERMINATED)", - "examples": [ - 0.35 - ] - }, - "locked": { - "type": "boolean", - "description": "Whether the pod is locked (prevents stopping or resetting)", - "examples": [ - false - ] - }, - "globalNetworking": { - "$ref": "#/components/schemas/PodGlobalNetworking" - }, - "runtime": { - "description": "Live utilization metrics. Null when the pod is not RUNNING.", - "anyOf": [ - { - "$ref": "#/components/schemas/PodRuntime" - }, - { - "type": "null" - } - ] - }, - "createdAt": { - "type": "string", - "format": "date-time", - "examples": [ - "2026-03-13T20:00:00Z" - ] - }, - "startedAt": { - "type": [ - "string", - "null" - ], - "format": "date-time", - "examples": [ - "2026-03-13T20:00:00Z" - ] - } - } - } - ] - }, - "CreatePodRequest": { - "allOf": [ - { - "$ref": "#/components/schemas/ContainerConfig" - }, - { - "type": "object", - "required": [ - "name", - "image" - ], - "description": "Request body for creating a pod. Exactly one of `gpu` or `cpu`\nmust be set — enforced at the handler layer. For CPU pods, memory\nis derived by the API from the selected flavor's RAM multiplier;\nclients provide only CPU flavor and vCPU count. CPU pods support\ncontainer disk and network volumes only; `mounts.persistent` is\ninvalid when `cpu` is set.\n", - "properties": { - "name": { - "type": "string", - "minLength": 1, - "examples": [ - "my-training-pod" - ] - }, - "mounts": { - "$ref": "#/components/schemas/Mounts" - }, - "gpu": { - "allOf": [ - { - "$ref": "#/components/schemas/GpuConfig" - } - ], - "unevaluatedProperties": false - }, - "cpu": { - "$ref": "#/components/schemas/CreateCpuConfig" - }, - "cloud": { - "allOf": [ - { - "$ref": "#/components/schemas/Cloud" - } - ], - "default": "SECURE", - "description": "Cloud tier. Defaults to `SECURE` when omitted." - }, - "dataCenterIds": { - "type": "array", - "items": { - "type": "string" - }, - "description": "Preferred data centers for placement. Omit or pass an empty\narray to let the scheduler choose.\n", - "examples": [ - [ - "US-TX-3" - ] - ] - }, - "globalNetworking": { - "type": "boolean", - "default": false, - "description": "Enable global networking, giving the pod a private IP reachable across data centers. Requires an NVIDIA GPU and a global-networking-enabled data center (both enforced upstream). See `GET /v2/catalog/datacenters` (`globalNetwork`) for eligible data centers.", - "examples": [ - false - ] - } - } - } - ], - "unevaluatedProperties": false - }, - "UpdatePodRequest": { - "allOf": [ - { - "$ref": "#/components/schemas/ContainerConfig" - }, - { - "type": "object", - "properties": { - "name": { - "type": "string", - "minLength": 1 - }, - "mounts": { - "$ref": "#/components/schemas/Mounts" - }, - "locked": { - "type": "boolean", - "description": "Lock the pod (true) or unlock it (false). Locked pods cannot be stopped or reset." - }, - "globalNetworking": { - "type": "boolean", - "description": "Enable (true) or disable (false) global networking. Takes effect on the next pod start/restart, not live. Requires an NVIDIA GPU and a global-networking-enabled data center (both enforced upstream). See `GET /v2/catalog/datacenters` (`globalNetwork`) for eligible data centers." - } - } - } - ], - "unevaluatedProperties": false - }, - "PodActionRequest": { - "type": "object", - "additionalProperties": false, - "required": [ - "action" - ], - "properties": { - "action": { - "$ref": "#/components/schemas/PodAction" - } - } - }, - "ListPodsResponse": { - "type": "object", - "required": [ - "pods" - ], - "properties": { - "pods": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Pod" - } - } - } - }, - "Template": { - "allOf": [ - { - "$ref": "#/components/schemas/ContainerConfig" - }, - { - "type": "object", - "required": [ - "id", - "name", - "image", - "args", - "disk", - "mounts", - "ports", - "env", - "registry", - "serverless", - "public", - "category" - ], - "properties": { - "id": { - "type": "string", - "examples": [ - "tpl_abc" - ] - }, - "name": { - "type": "string", - "examples": [ - "My PyTorch Template" - ] - }, - "mounts": { - "$ref": "#/components/schemas/TemplateMounts" - }, - "serverless": { - "type": "boolean", - "description": "Whether this template is for serverless workers (true) or pods (false)", - "examples": [ - false - ] - }, - "public": { - "type": "boolean", - "description": "Whether this template is visible to other Runpod users", - "examples": [ - false - ] - }, - "category": { - "$ref": "#/components/schemas/TemplateCategory" - } - } - } - ] - }, - "CreateTemplateRequest": { - "allOf": [ - { - "$ref": "#/components/schemas/ContainerConfig" - }, - { - "type": "object", - "required": [ - "name", - "image" - ], - "properties": { - "name": { - "type": "string", - "minLength": 1, - "examples": [ - "My PyTorch Template" - ] - }, - "mounts": { - "$ref": "#/components/schemas/TemplateMounts" - }, - "serverless": { - "type": "boolean", - "default": false - }, - "public": { - "type": "boolean", - "default": false - }, - "category": { - "description": "Optional. Defaults to `NVIDIA` when omitted.", - "allOf": [ - { - "$ref": "#/components/schemas/TemplateCategory" - } - ], - "default": "NVIDIA" - } - } - } - ], - "unevaluatedProperties": false - }, - "UpdateTemplateRequest": { - "allOf": [ - { - "$ref": "#/components/schemas/ContainerConfig" - }, - { - "type": "object", - "properties": { - "name": { - "type": "string", - "minLength": 1 - }, - "mounts": { - "$ref": "#/components/schemas/TemplateMounts" - }, - "serverless": { - "type": "boolean" - }, - "public": { - "type": "boolean" - }, - "category": { - "$ref": "#/components/schemas/TemplateCategory" - } - } - } - ], - "unevaluatedProperties": false - }, - "ListTemplatesResponse": { - "type": "object", - "required": [ - "templates" - ], - "properties": { - "templates": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Template" - } - } - } - }, - "NetworkVolume": { - "type": "object", - "required": [ - "id", - "name", - "size", - "dataCenter", - "type" - ], - "properties": { - "id": { - "type": "string", - "description": "Unique network volume identifier", - "examples": [ - "agv6w2qcg7" - ] - }, - "name": { - "type": "string", - "description": "Human-readable name (not required to be unique)", - "examples": [ - "my-dataset" - ] - }, - "size": { - "type": "integer", - "minimum": 10, - "maximum": 4096, - "description": "Allocated storage in GB", - "examples": [ - 50 - ] - }, - "dataCenter": { - "type": "string", - "description": "Data center location; immutable after creation", - "examples": [ - "EU-RO-1" - ] - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/VolumeType" - } - ], - "description": "Storage tier of this volume. Set at creation and immutable." - } - } - }, - "CreateNetworkVolumeRequest": { - "type": "object", - "additionalProperties": false, - "required": [ - "name", - "size", - "dataCenter" - ], - "properties": { - "name": { - "type": "string", - "minLength": 1, - "description": "Human-readable name", - "examples": [ - "my-dataset" - ] - }, - "size": { - "type": "integer", - "minimum": 10, - "maximum": 4096, - "description": "Storage to allocate in GB", - "examples": [ - 50 - ] - }, - "dataCenter": { - "type": "string", - "minLength": 1, - "description": "Data center in which to create the volume", - "examples": [ - "EU-RO-1" - ] - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/VolumeType" - } - ], - "description": "Storage tier for the volume. Optional. When omitted, the volume is\nprovisioned using the requested data center's default (primary)\nstorage tier. HIGH_PERFORMANCE provisions a high-performance (HPS)\nvolume; STANDARD provisions a standard volume. A volume's tier is\nimmutable after creation.\n" - } - } - }, - "UpdateNetworkVolumeRequest": { - "type": "object", - "additionalProperties": false, - "minProperties": 1, - "description": "Only the provided fields are updated. At least one field must be\npresent; an empty body is rejected.\n", - "properties": { - "name": { - "type": "string", - "minLength": 1, - "description": "New human-readable name", - "examples": [ - "renamed-volume" - ] - }, - "size": { - "type": "integer", - "minimum": 10, - "maximum": 4096, - "description": "New size in GB. Must be greater than or equal to the current size —\nnetwork volume storage cannot be reduced.\n", - "examples": [ - 100 - ] - } - } - }, - "ListNetworkVolumesResponse": { - "type": "object", - "required": [ - "networkVolumes" - ], - "properties": { - "networkVolumes": { - "type": "array", - "items": { - "$ref": "#/components/schemas/NetworkVolume" - } - } - } - }, - "Registry": { - "type": "object", - "required": [ - "id", - "name" - ], - "properties": { - "id": { - "type": "string", - "examples": [ - "reg_abc" - ] - }, - "name": { - "type": "string", - "examples": [ - "my-private-registry" - ] - } - } - }, - "CreateRegistryRequest": { - "type": "object", - "additionalProperties": false, - "required": [ - "name", - "username", - "password" - ], - "properties": { - "name": { - "type": "string", - "minLength": 1, - "examples": [ - "my-private-registry" - ] - }, - "username": { - "type": "string", - "minLength": 1, - "description": "Registry username (write-only, not returned in responses)" - }, - "password": { - "type": "string", - "minLength": 1, - "description": "Registry password (write-only, not returned in responses)" - } - } - }, - "ListRegistriesResponse": { - "type": "object", - "required": [ - "registries" - ], - "properties": { - "registries": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Registry" - } - } - } - }, - "EcrDelegation": { - "type": "object", - "required": [ - "id", - "delegatorUserId", - "awsUser", - "repository", - "tag", - "awsRegion", - "createdAt" - ], - "properties": { - "id": { - "type": "string", - "description": "Delegation identifier", - "examples": [ - "deleg_abc123" - ] - }, - "name": { - "type": [ - "string", - "null" - ], - "description": "Optional name for the delegation", - "examples": [ - "my-delegation" - ] - }, - "delegatorUserId": { - "type": "string", - "description": "User ID that created the delegation", - "examples": [ - "user_xyz" - ] - }, - "awsUser": { - "type": "string", - "description": "AWS user/role being delegated", - "examples": [ - "123456789" - ] - }, - "repository": { - "type": "string", - "description": "ECR repository name", - "examples": [ - "runpod/deployment" - ] - }, - "tag": { - "type": "string", - "description": "ECR image tag", - "examples": [ - "latest" - ] - }, - "awsRegion": { - "type": "string", - "description": "AWS region", - "examples": [ - "us-east-2" - ] - }, - "dockerRegistryUri": { - "type": "string", - "description": "Formatted ECR registry URI for Docker login", - "examples": [ - "123456789.dkr.ecr.us-east-2.amazonaws.com" - ] - }, - "createdAt": { - "type": "string", - "format": "date-time", - "description": "When the delegation was created", - "examples": [ - "2026-03-13T20:00:00Z" - ] - } - } - }, - "CreateDelegationRequest": { - "type": "object", - "additionalProperties": false, - "required": [ - "resource" - ], - "properties": { - "resource": { - "type": "string", - "description": "ECR resource ARN", - "examples": [ - "arn:aws:ecr:us-east-2:418399314813:repository/runpod/deployment" - ] - }, - "name": { - "type": [ - "string", - "null" - ], - "description": "Optional name for the delegation", - "examples": [ - "my-delegation" - ] - } - } - }, - "ListDelegationsResponse": { - "type": "object", - "required": [ - "delegations" - ], - "properties": { - "delegations": { - "type": "array", - "items": { - "$ref": "#/components/schemas/EcrDelegation" - } - } - } - }, - "GpuManufacturer": { - "type": "string", - "description": "Canonical GPU hardware manufacturer.", - "x-enum-varnames": [ - "GpuManufacturerNVIDIA", - "GpuManufacturerAMD", - "GpuManufacturerUNKNOWN" - ], - "enum": [ - "NVIDIA", - "AMD", - "UNKNOWN" - ] - }, - "GpuType": { - "type": "object", - "required": [ - "id", - "name", - "pool", - "manufacturer", - "memory", - "secure", - "community", - "price", - "maxCount" - ], - "properties": { - "id": { - "type": "string", - "description": "Individual GPU type identifier (use for pod creation)", - "examples": [ - "NVIDIA GeForce RTX 4090" - ] - }, - "name": { - "type": "string", - "examples": [ - "RTX 4090" - ] - }, - "pool": { - "type": [ - "string", - "null" - ], - "description": "Serverless GPU pool ID (use for serverless endpoint creation). Null if GPU is not in a serverless pool.", - "examples": [ - "ADA_24" - ] - }, - "manufacturer": { - "$ref": "#/components/schemas/GpuManufacturer" - }, - "memory": { - "type": "integer", - "description": "VRAM in GB", - "examples": [ - 24 - ] - }, - "secure": { - "type": "boolean", - "description": "Available on secure cloud", - "examples": [ - true - ] - }, - "community": { - "type": "boolean", - "description": "Available on community cloud", - "examples": [ - true - ] - }, - "price": { - "type": "object", - "required": [ - "secure", - "community" - ], - "properties": { - "secure": { - "type": "number", - "format": "float", - "examples": [ - 0.44 - ] - }, - "community": { - "type": "number", - "format": "float", - "examples": [ - 0.31 - ] - } - } - }, - "maxCount": { - "type": "object", - "required": [ - "secure", - "community" - ], - "properties": { - "secure": { - "type": "integer", - "examples": [ - 8 - ] - }, - "community": { - "type": "integer", - "examples": [ - 4 - ] - } - } - }, - "availability": { - "description": "Overall GPU availability. Present only when requested with include=AVAILABILITY.", - "$ref": "#/components/schemas/AvailabilityLevel" - }, - "dataCenters": { - "type": "array", - "description": "Per-datacenter GPU availability. Present only when requested with include=AVAILABILITY.", - "items": { - "$ref": "#/components/schemas/DataCenterAvailability" - } - } - } - }, - "AvailabilityLevel": { - "type": "string", - "description": "Catalog stock availability level.", - "enum": [ - "NONE", - "LOW", - "MEDIUM", - "HIGH" - ] - }, - "Product": { - "type": "string", - "description": "Catalog product availability context.", - "enum": [ - "POD", - "CLUSTER", - "SERVERLESS" - ] - }, - "CpuProduct": { - "type": "string", - "description": "CPU catalog product availability context.", - "enum": [ - "POD", - "SERVERLESS" - ] - }, - "CatalogInclude": { - "type": "string", - "description": "Catalog include expansion. Only AVAILABILITY is supported today; additional include values may be added in the future.", - "enum": [ - "AVAILABILITY" - ] - }, - "DataCenterInclude": { - "type": "string", - "description": "Data center catalog availability expansion.", - "enum": [ - "GPU_AVAILABILITY", - "CPU_AVAILABILITY" - ] - }, - "GpuCloudFilter": { - "type": "string", - "description": "GPU availability cloud filter.", - "enum": [ - "SECURE", - "COMMUNITY" - ] - }, - "VolumeType": { - "type": "string", - "description": "Data center network volume storage type.", - "enum": [ - "STANDARD", - "HIGH_PERFORMANCE" - ] - }, - "CatalogResourceAvailability": { - "type": "object", - "required": [ - "id", - "name", - "availability" - ], - "properties": { - "id": { - "type": "string", - "description": "Catalog resource identifier.", - "examples": [ - "NVIDIA GeForce RTX 4090" - ] - }, - "name": { - "type": "string", - "description": "Human-readable catalog resource name.", - "examples": [ - "RTX 4090" - ] - }, - "availability": { - "$ref": "#/components/schemas/AvailabilityLevel" - } - } - }, - "DataCenterAvailability": { - "type": "object", - "required": [ - "id", - "name", - "availability" - ], - "properties": { - "id": { - "type": "string", - "description": "Data center identifier.", - "examples": [ - "US-CA-2" - ] - }, - "name": { - "type": "string", - "description": "Human-readable data center name.", - "examples": [ - "US California 2" - ] - }, - "availability": { - "$ref": "#/components/schemas/AvailabilityLevel" - } - } - }, - "ListGpuTypesResponse": { - "type": "object", - "required": [ - "gpus" - ], - "properties": { - "gpus": { - "type": "array", - "items": { - "$ref": "#/components/schemas/GpuType" - } - } - } - }, - "CpuType": { - "type": "object", - "required": [ - "id", - "name", - "group", - "vcpu", - "ramGbPerVcpu", - "price" - ], - "properties": { - "id": { - "type": "string", - "description": "CPU flavor identifier (use in cpu.id for pod creation)", - "examples": [ - "cpu5c" - ] - }, - "name": { - "type": "string", - "description": "Human-readable flavor name", - "examples": [ - "Compute-Optimized" - ] - }, - "group": { - "type": "string", - "description": "CPU generation group", - "examples": [ - "Gen 5" - ] - }, - "vcpu": { - "type": "object", - "required": [ - "min", - "max" - ], - "properties": { - "min": { - "type": "integer", - "examples": [ - 2 - ] - }, - "max": { - "type": "integer", - "examples": [ - 32 - ] - } - } - }, - "ramGbPerVcpu": { - "type": "number", - "format": "float", - "description": "GB of RAM allocated per vCPU. Multiply by the chosen vCPU\ncount (within `vcpu.min`..`vcpu.max`) to get the total RAM\nfor an instance of this flavor. May be fractional.\n", - "examples": [ - 2.5 - ] - }, - "price": { - "type": "object", - "required": [ - "securePerVcpu", - "serverlessPerVcpu" - ], - "properties": { - "securePerVcpu": { - "type": "number", - "format": "float", - "description": "Price for secure pods per vCPU. Multiply by the chosen vCPU\ncount (within `vcpu.min`..`vcpu.max`) to get the total price.\n", - "examples": [ - 0.04 - ] - }, - "serverlessPerVcpu": { - "type": "number", - "format": "float", - "description": "Price for serverless per vCPU. Multiply by the chosen vCPU\ncount (within `vcpu.min`..`vcpu.max`) to get the total price.\n", - "examples": [ - 0.03 - ] - } - } - }, - "availability": { - "description": "Overall CPU availability. Present only when requested with include=AVAILABILITY.", - "$ref": "#/components/schemas/AvailabilityLevel" - }, - "dataCenters": { - "type": "array", - "description": "Per-datacenter CPU availability. Present only when requested with include=AVAILABILITY.", - "items": { - "$ref": "#/components/schemas/DataCenterAvailability" - } - } - } - }, - "ListCpuTypesResponse": { - "type": "object", - "required": [ - "cpus" - ], - "properties": { - "cpus": { - "type": "array", - "items": { - "$ref": "#/components/schemas/CpuType" - } - } - } - }, - "DataCenter": { - "type": "object", - "required": [ - "id", - "name", - "region", - "networkVolumeTypes", - "compliance", - "globalNetwork" - ], - "properties": { - "id": { - "type": "string", - "examples": [ - "US-TX-3" - ] - }, - "name": { - "type": "string", - "examples": [ - "US Texas 3" - ] - }, - "region": { - "$ref": "#/components/schemas/DataCenterRegion" - }, - "globalNetwork": { - "type": "boolean", - "description": "Whether this data center supports global networking (private cross-datacenter pod-to-pod network).", - "examples": [ - true - ] - }, - "networkVolumeTypes": { - "type": "array", - "items": { - "$ref": "#/components/schemas/VolumeType" - }, - "description": "Network volume tiers this DC supports. Empty = none." - }, - "compliance": { - "type": "array", - "description": "Compliance certifications held by this data center", - "items": { - "$ref": "#/components/schemas/Compliance" - }, - "examples": [ - [ - "GDPR", - "ISO_IEC_27001", - "SOC_2_TYPE_2" - ] - ] - }, - "gpuAvailability": { - "type": "array", - "description": "Per-GPU availability in this data center. Present only when requested with include=GPU_AVAILABILITY.", - "items": { - "$ref": "#/components/schemas/CatalogResourceAvailability" - } - }, - "cpuAvailability": { - "type": "array", - "description": "Per-CPU availability in this data center. Present only when requested with include=CPU_AVAILABILITY.", - "items": { - "$ref": "#/components/schemas/CatalogResourceAvailability" - } - } - } - }, - "DataCenterRegion": { - "type": "string", - "description": "Continental region containing the data center.", - "examples": [ - "EUROPE" - ], - "enum": [ - "NORTH_AMERICA", - "SOUTH_AMERICA", - "EUROPE", - "ASIA", - "MIDDLE_EAST", - "AFRICA", - "OCEANIA", - "ANTARCTICA", - "UNKNOWN" - ] - }, - "Compliance": { - "type": "string", - "description": "Compliance certifications.", - "enum": [ - "GDPR", - "ISO_IEC_27001", - "ISO_14001", - "PCI_DSS", - "HITRUST", - "SOC_1_TYPE_2", - "SOC_2_TYPE_2", - "SOC_3_TYPE_2", - "ITAR", - "FISMA_HIGH", - "HIPAA", - "RENEWABLE" - ] - }, - "ListDataCentersResponse": { - "type": "object", - "required": [ - "dataCenters" - ], - "properties": { - "dataCenters": { - "type": "array", - "items": { - "$ref": "#/components/schemas/DataCenter" - } - } - } - }, - "BillingTimeRange": { - "type": "object", - "description": "Half-open time range [startTime, endTime) in RFC 3339. On a record it is the time bucket; on a query echo it is the resolved window.\n", - "required": [ - "startTime", - "endTime" - ], - "properties": { - "startTime": { - "type": "string", - "format": "date-time", - "description": "Start of the range, inclusive (RFC 3339).", - "examples": [ - "2026-06-01T00:00:00Z" - ] - }, - "endTime": { - "type": "string", - "format": "date-time", - "description": "End of the range, exclusive (RFC 3339).", - "examples": [ - "2026-06-02T00:00:00Z" - ] - } - } - }, - "BillingBucketSize": { - "type": "string", - "enum": [ - "hour", - "day", - "week", - "month", - "year" - ], - "x-enum-varnames": [ - "BillingBucketSizeHour", - "BillingBucketSizeDay", - "BillingBucketSizeWeek", - "BillingBucketSizeMonth", - "BillingBucketSizeYear" - ], - "default": "day", - "description": "Length of each billing time bucket.", - "examples": [ - "day" - ] - }, - "BillingAmounts": { - "type": "object", - "description": "Total spend across all billable Runpod resources with each cost component broken out, fully prefixed by resource. Backs the aggregate record's amounts and the metadata totals.\n", - "required": [ - "totalAmount", - "podGpuAmount", - "podCpuAmount", - "podDiskAmount", - "serverlessGpuAmount", - "serverlessCpuAmount", - "serverlessDiskAmount", - "serverlessFeeAmount", - "storageStandardAmount", - "storageHighPerformanceAmount", - "endpointAmount", - "clusterGpuAmount", - "clusterDiskAmount", - "clusterNetworkingAmount" - ], - "properties": { - "totalAmount": { - "type": "number", - "format": "double", - "description": "Total cost in USD for the bucket across all resources.", - "examples": [ - 42.34 - ] - }, - "podGpuAmount": { - "type": "number", - "format": "double", - "description": "GPU pod compute cost in USD for the bucket." - }, - "podCpuAmount": { - "type": "number", - "format": "double", - "description": "CPU pod compute cost in USD for the bucket." - }, - "podDiskAmount": { - "type": "number", - "format": "double", - "description": "Pod disk cost in USD for the bucket." - }, - "serverlessGpuAmount": { - "type": "number", - "format": "double", - "description": "Serverless GPU compute cost in USD for the bucket." - }, - "serverlessCpuAmount": { - "type": "number", - "format": "double", - "description": "Serverless CPU compute cost in USD for the bucket." - }, - "serverlessDiskAmount": { - "type": "number", - "format": "double", - "description": "Serverless disk cost in USD for the bucket." - }, - "serverlessFeeAmount": { - "type": "number", - "format": "double", - "description": "Serverless platform fee in USD for the bucket." - }, - "storageStandardAmount": { - "type": "number", - "format": "double", - "description": "Standard network volume storage cost in USD for the bucket." - }, - "storageHighPerformanceAmount": { - "type": "number", - "format": "double", - "description": "High-performance network volume storage cost in USD for the bucket." - }, - "endpointAmount": { - "type": "number", - "format": "double", - "description": "Runpod public endpoint cost in USD for the bucket." - }, - "clusterGpuAmount": { - "type": "number", - "format": "double", - "description": "Instant Cluster GPU compute cost in USD for the bucket." - }, - "clusterDiskAmount": { - "type": "number", - "format": "double", - "description": "Instant Cluster disk cost in USD for the bucket." - }, - "clusterNetworkingAmount": { - "type": "number", - "format": "double", - "description": "Instant Cluster inter-node networking cost in USD for the bucket." - } - } - }, - "BillingRecord": { - "description": "A single time-bucketed record of total spend across all billable Runpod resources, with each cost component broken out. Returned by GET /v2/billing.\n", - "allOf": [ - { - "$ref": "#/components/schemas/BillingTimeRange" - }, - { - "$ref": "#/components/schemas/BillingAmounts" - } - ] - }, - "PodBillingAmounts": { - "type": "object", - "description": "Pod cost components covering both GPU and CPU pods. Backs a record's amounts and the metadata totals.\n", - "required": [ - "totalAmount", - "gpuAmount", - "cpuAmount", - "diskAmount" - ], - "properties": { - "totalAmount": { - "type": "number", - "format": "double", - "description": "Total pod cost in USD for the bucket.", - "examples": [ - 12.34 - ] - }, - "gpuAmount": { - "type": "number", - "format": "double", - "description": "GPU pod compute cost in USD for the bucket." - }, - "cpuAmount": { - "type": "number", - "format": "double", - "description": "CPU pod compute cost in USD for the bucket." - }, - "diskAmount": { - "type": "number", - "format": "double", - "description": "Pod disk cost in USD for the bucket." - } - } - }, - "PodBillingRecord": { - "description": "A single time-bucketed pod billing record, covering both GPU and CPU pods. Returned by GET /v2/billing/pods.\n", - "allOf": [ - { - "$ref": "#/components/schemas/BillingTimeRange" - }, - { - "$ref": "#/components/schemas/PodBillingAmounts" - }, - { - "type": "object", - "required": [ - "podId" - ], - "properties": { - "podId": { - "type": "string", - "description": "The pod this record bills. When the podId filter is set every record carries that id; otherwise one record is emitted per pod per bucket.\n", - "examples": [ - "pod_abc123" - ] - } - } - } - ] - }, - "ServerlessBillingAmounts": { - "type": "object", - "description": "Serverless cost components. Backs a record's amounts and the metadata totals.\n", - "required": [ - "totalAmount", - "gpuAmount", - "cpuAmount", - "diskAmount", - "feeAmount" - ], - "properties": { - "totalAmount": { - "type": "number", - "format": "double", - "description": "Total serverless cost in USD for the bucket.", - "examples": [ - 8.9 - ] - }, - "gpuAmount": { - "type": "number", - "format": "double", - "description": "Serverless GPU compute cost in USD for the bucket." - }, - "cpuAmount": { - "type": "number", - "format": "double", - "description": "Serverless CPU compute cost in USD for the bucket." - }, - "diskAmount": { - "type": "number", - "format": "double", - "description": "Serverless disk cost in USD for the bucket." - }, - "feeAmount": { - "type": "number", - "format": "double", - "description": "Serverless platform fee in USD for the bucket." - } - } - }, - "ServerlessBillingRecord": { - "description": "A single time-bucketed serverless billing record. Returned by GET /v2/billing/serverless.\n", - "allOf": [ - { - "$ref": "#/components/schemas/BillingTimeRange" - }, - { - "$ref": "#/components/schemas/ServerlessBillingAmounts" - }, - { - "type": "object", - "required": [ - "serverlessId" - ], - "properties": { - "serverlessId": { - "type": "string", - "description": "The serverless endpoint this record bills. When the serverlessId filter is set every record carries that id; otherwise one record is emitted per serverless endpoint per bucket.\n", - "examples": [ - "ep_abc123" - ] - } - } - } - ] - }, - "EndpointBillingAmounts": { - "type": "object", - "description": "Runpod public endpoint cost. Backs a record's amounts and the metadata totals.\n", - "required": [ - "totalAmount" - ], - "properties": { - "totalAmount": { - "type": "number", - "format": "double", - "description": "Total public endpoint cost in USD for the bucket.", - "examples": [ - 3.21 - ] - } - } - }, - "EndpointBillingRecord": { - "description": "A single time-bucketed Runpod public endpoint billing record. Returned by GET /v2/billing/endpoints.\n", - "allOf": [ - { - "$ref": "#/components/schemas/BillingTimeRange" - }, - { - "$ref": "#/components/schemas/EndpointBillingAmounts" - } - ] - }, - "NetworkVolumeBillingAmounts": { - "type": "object", - "description": "Network volume storage cost, split into standard and high-performance. Backs a record's amounts and the metadata totals.\n", - "required": [ - "totalAmount", - "standardAmount", - "highPerformanceAmount" - ], - "properties": { - "totalAmount": { - "type": "number", - "format": "double", - "description": "Total network volume cost in USD for the bucket, across standard and high-performance storage.\n", - "examples": [ - 5.79 - ] - }, - "standardAmount": { - "type": "number", - "format": "double", - "description": "Standard storage cost in USD for the bucket." - }, - "highPerformanceAmount": { - "type": "number", - "format": "double", - "description": "High-performance storage cost in USD for the bucket." - } - } - }, - "NetworkVolumeBillingRecord": { - "description": "A single time-bucketed network volume billing record, split into standard and high-performance storage. Returned by GET /v2/billing/networkvolumes.\n", - "allOf": [ - { - "$ref": "#/components/schemas/BillingTimeRange" - }, - { - "$ref": "#/components/schemas/NetworkVolumeBillingAmounts" - }, - { - "type": "object", - "required": [ - "networkVolumeId" - ], - "properties": { - "networkVolumeId": { - "type": "string", - "description": "The network volume this record bills. When the networkVolumeId filter is set every record carries that id; otherwise one record is emitted per network volume per bucket.\n", - "examples": [ - "vol_abc123" - ] - } - } - } - ] - }, - "ClusterBillingAmounts": { - "type": "object", - "description": "Instant Cluster cost components (GPU-only, no CPU). Backs a record's amounts and the metadata totals.\n", - "required": [ - "totalAmount", - "gpuAmount", - "diskAmount", - "networkingAmount" - ], - "properties": { - "totalAmount": { - "type": "number", - "format": "double", - "description": "Total Instant Cluster cost in USD for the bucket.", - "examples": [ - 99 - ] - }, - "gpuAmount": { - "type": "number", - "format": "double", - "description": "Cluster GPU compute cost in USD for the bucket." - }, - "diskAmount": { - "type": "number", - "format": "double", - "description": "Cluster disk cost in USD for the bucket." - }, - "networkingAmount": { - "type": "number", - "format": "double", - "description": "Cluster inter-node networking cost in USD for the bucket." - } - } - }, - "ClusterBillingRecord": { - "description": "A single time-bucketed Instant Cluster billing record. Clusters are GPU-only (no CPU component). Returned by GET /v2/billing/clusters.\n", - "allOf": [ - { - "$ref": "#/components/schemas/BillingTimeRange" - }, - { - "$ref": "#/components/schemas/ClusterBillingAmounts" - }, - { - "type": "object", - "required": [ - "clusterId" - ], - "properties": { - "clusterId": { - "type": "string", - "description": "The Instant Cluster this record bills. When the clusterId filter is set every record carries that id; otherwise one record is emitted per cluster per bucket.\n", - "examples": [ - "cluster_abc123" - ] - } - } - } - ] - }, - "BillingQuery": { - "description": "Resolved query window and granularity (routes without a filter).", - "allOf": [ - { - "$ref": "#/components/schemas/BillingTimeRange" - }, - { - "type": "object", - "required": [ - "bucketSize" - ], - "properties": { - "bucketSize": { - "$ref": "#/components/schemas/BillingBucketSize" - } - } - } - ] - }, - "PodBillingQuery": { - "allOf": [ - { - "$ref": "#/components/schemas/BillingQuery" - }, - { - "type": "object", - "properties": { - "podId": { - "type": [ - "string", - "null" - ], - "description": "The podId filter applied, if any." - } - } - } - ] - }, - "ServerlessBillingQuery": { - "allOf": [ - { - "$ref": "#/components/schemas/BillingQuery" - }, - { - "type": "object", - "properties": { - "serverlessId": { - "type": [ - "string", - "null" - ], - "description": "The serverlessId filter applied, if any." - } - } - } - ] - }, - "NetworkVolumeBillingQuery": { - "allOf": [ - { - "$ref": "#/components/schemas/BillingQuery" - }, - { - "type": "object", - "properties": { - "networkVolumeId": { - "type": [ - "string", - "null" - ], - "description": "The networkVolumeId filter applied, if any." - } - } - } - ] - }, - "ClusterBillingQuery": { - "allOf": [ - { - "$ref": "#/components/schemas/BillingQuery" - }, - { - "type": "object", - "properties": { - "clusterId": { - "type": [ - "string", - "null" - ], - "description": "The clusterId filter applied, if any." - } - } - } - ] - }, - "BillingMetadata": { - "type": "object", - "required": [ - "query", - "recordCount", - "totals" - ], - "properties": { - "query": { - "$ref": "#/components/schemas/BillingQuery" - }, - "recordCount": { - "type": "integer", - "description": "Number of records returned." - }, - "totals": { - "$ref": "#/components/schemas/BillingAmounts" - } - } - }, - "PodBillingMetadata": { - "type": "object", - "required": [ - "query", - "recordCount", - "uniquePodCount", - "totals" - ], - "properties": { - "query": { - "$ref": "#/components/schemas/PodBillingQuery" - }, - "recordCount": { - "type": "integer", - "description": "Number of records returned (buckets times distinct pods)." - }, - "uniquePodCount": { - "type": "integer", - "description": "Number of distinct pods the records span." - }, - "totals": { - "$ref": "#/components/schemas/PodBillingAmounts" - } - } - }, - "ServerlessBillingMetadata": { - "type": "object", - "required": [ - "query", - "recordCount", - "uniqueServerlessCount", - "totals" - ], - "properties": { - "query": { - "$ref": "#/components/schemas/ServerlessBillingQuery" - }, - "recordCount": { - "type": "integer", - "description": "Number of records returned (buckets times distinct endpoints)." - }, - "uniqueServerlessCount": { - "type": "integer", - "description": "Number of distinct serverless endpoints the records span." - }, - "totals": { - "$ref": "#/components/schemas/ServerlessBillingAmounts" - } - } - }, - "EndpointBillingMetadata": { - "type": "object", - "required": [ - "query", - "recordCount", - "totals" - ], - "properties": { - "query": { - "$ref": "#/components/schemas/BillingQuery" - }, - "recordCount": { - "type": "integer" - }, - "totals": { - "$ref": "#/components/schemas/EndpointBillingAmounts" - } - } - }, - "NetworkVolumeBillingMetadata": { - "type": "object", - "required": [ - "query", - "recordCount", - "uniqueNetworkVolumeCount", - "totals" - ], - "properties": { - "query": { - "$ref": "#/components/schemas/NetworkVolumeBillingQuery" - }, - "recordCount": { - "type": "integer", - "description": "Number of records returned (buckets times distinct volumes)." - }, - "uniqueNetworkVolumeCount": { - "type": "integer", - "description": "Number of distinct network volumes the records span." - }, - "totals": { - "$ref": "#/components/schemas/NetworkVolumeBillingAmounts" - } - } - }, - "ClusterBillingMetadata": { - "type": "object", - "required": [ - "query", - "recordCount", - "uniqueClusterCount", - "totals" - ], - "properties": { - "query": { - "$ref": "#/components/schemas/ClusterBillingQuery" - }, - "recordCount": { - "type": "integer", - "description": "Number of records returned (buckets times distinct clusters)." - }, - "uniqueClusterCount": { - "type": "integer", - "description": "Number of distinct clusters the records span." - }, - "totals": { - "$ref": "#/components/schemas/ClusterBillingAmounts" - } - } - }, - "ListBillingResponse": { - "type": "object", - "description": "Aggregated billing records across all Runpod resources.", - "required": [ - "records", - "metadata" - ], - "properties": { - "records": { - "type": "array", - "items": { - "$ref": "#/components/schemas/BillingRecord" - } - }, - "metadata": { - "$ref": "#/components/schemas/BillingMetadata" - } - } - }, - "ListPodBillingResponse": { - "type": "object", - "description": "Billing records for pods.", - "required": [ - "records", - "metadata" - ], - "properties": { - "records": { - "type": "array", - "items": { - "$ref": "#/components/schemas/PodBillingRecord" - } - }, - "metadata": { - "$ref": "#/components/schemas/PodBillingMetadata" - } - } - }, - "ListServerlessBillingResponse": { - "type": "object", - "description": "Billing records for serverless.", - "required": [ - "records", - "metadata" - ], - "properties": { - "records": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ServerlessBillingRecord" - } - }, - "metadata": { - "$ref": "#/components/schemas/ServerlessBillingMetadata" - } - } - }, - "ListEndpointBillingResponse": { - "type": "object", - "description": "Time-bucketed Runpod public endpoint billing records plus metadata for the resolved query, record count, and total endpoint amount.\n", - "required": [ - "records", - "metadata" - ], - "properties": { - "records": { - "type": "array", - "items": { - "$ref": "#/components/schemas/EndpointBillingRecord" - } - }, - "metadata": { - "$ref": "#/components/schemas/EndpointBillingMetadata" - } - } - }, - "ListNetworkVolumeBillingResponse": { - "type": "object", - "description": "Time-bucketed network volume billing records plus metadata for the resolved query, record count, distinct volume count, and storage totals.\n", - "required": [ - "records", - "metadata" - ], - "properties": { - "records": { - "type": "array", - "items": { - "$ref": "#/components/schemas/NetworkVolumeBillingRecord" - } - }, - "metadata": { - "$ref": "#/components/schemas/NetworkVolumeBillingMetadata" - } - } - }, - "ListClusterBillingResponse": { - "type": "object", - "description": "Time-bucketed Instant Cluster billing records plus metadata for the resolved query, record count, distinct cluster count, and compute totals.\n", - "required": [ - "records", - "metadata" - ], - "properties": { - "records": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ClusterBillingRecord" - } - }, - "metadata": { - "$ref": "#/components/schemas/ClusterBillingMetadata" - } - } - }, - "ErrorResponse": { - "type": "object", - "required": [ - "title", - "status", - "detail" - ], - "properties": { - "title": { - "type": "string", - "description": "Short human-readable summary", - "examples": [ - "Not Found" - ] - }, - "status": { - "type": "integer", - "description": "HTTP status code", - "examples": [ - 404 - ] - }, - "detail": { - "type": "string", - "description": "Human-readable explanation", - "examples": [ - "pod not found" - ] - }, - "errors": { - "type": "array", - "description": "Individual request-validation failures.", - "items": { - "type": "string" - }, - "examples": [ - [ - "$: additional properties 'bogus' not allowed" - ] - ] - } - } - } - } - }, - "paths": { - "/v2/pods": { - "get": { - "operationId": "listPods", - "summary": "List pods", - "description": "Returns all pods owned by the authenticated user.", - "tags": [ - "Pods" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ListPodsResponse" - }, - "examples": { - "pods": { - "summary": "Successful response", - "value": { - "pods": [ - { - "id": "7h9k2m4n6p", - "name": "pytorch-training", - "image": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1", - "args": "", - "disk": 50, - "ports": [ - "8888/http", - "22/tcp" - ], - "env": { - "MODEL_NAME": "llama-3" - }, - "registry": null, - "status": "RUNNING", - "actions": [ - "stop", - "restart", - "terminate" - ], - "mounts": { - "persistent": { - "size": 20, - "path": "/workspace" - } - }, - "gpu": { - "id": "NVIDIA GeForce RTX 4090", - "count": 1 - }, - "cloud": "SECURE", - "dataCenterId": "US-KS-2", - "template": "9x4m2p7v", - "cost": 0.44, - "locked": false, - "globalNetworking": { - "enabled": false - }, - "runtime": { - "uptime": 3600 - }, - "createdAt": "2026-06-01T12:00:00Z", - "startedAt": "2026-06-01T12:02:00Z" - } - ] - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "403": { - "$ref": "#/components/responses/ForbiddenError" - }, - "429": { - "$ref": "#/components/responses/TooManyRequestsError" - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - }, - "post": { - "operationId": "createPod", - "summary": "Create a pod", - "description": "Creates a new pod. `name` and `image` are always required; supply\nexactly one of `gpu` or `cpu` to select compute (a GPU or a CPU pod).\nRemaining container settings can be spread from a template response —\nsee `CreatePodRequest` for the full body.\n\nReturns `201` with the created pod. Provisioning is asynchronous: the\npod starts in `PROVISIONING`, transitions through `STARTING`, and\nreaches `RUNNING` once its container is healthy. Poll `getPod` (or\nwatch the pod's `status`) to observe readiness rather than assuming\nthe pod is running when this call returns.\n", - "tags": [ - "Pods" - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CreatePodRequest" - }, - "examples": { - "gpuPod": { - "summary": "GPU pod", - "value": { - "name": "pytorch-training", - "image": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1", - "gpu": { - "id": "NVIDIA GeForce RTX 4090", - "count": 1 - }, - "disk": 50 - } - } - } - } - } - }, - "responses": { - "201": { - "description": "Created", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Pod" - }, - "examples": { - "pod": { - "summary": "Successful response", - "value": { - "id": "7h9k2m4n6p", - "name": "pytorch-training", - "image": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1", - "args": "", - "disk": 50, - "ports": [ - "8888/http", - "22/tcp" - ], - "env": { - "MODEL_NAME": "llama-3" - }, - "registry": null, - "status": "PROVISIONING", - "actions": [ - "start", - "terminate" - ], - "mounts": { - "persistent": { - "size": 20, - "path": "/workspace" - } - }, - "gpu": { - "id": "NVIDIA GeForce RTX 4090", - "count": 1 - }, - "cloud": "SECURE", - "dataCenterId": "US-KS-2", - "template": "9x4m2p7v", - "cost": 0.44, - "locked": false, - "globalNetworking": { - "enabled": false - }, - "runtime": {}, - "createdAt": "2026-06-01T12:00:00Z", - "startedAt": null - } - } - } - } - } - }, - "400": { - "$ref": "#/components/responses/BadRequestError" - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "403": { - "$ref": "#/components/responses/ForbiddenError" - }, - "422": { - "$ref": "#/components/responses/UnprocessableEntityError" - }, - "429": { - "$ref": "#/components/responses/TooManyRequestsError" - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - } - }, - "/v2/pods/{id}": { - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - }, - "description": "Pod identifier", - "example": "pod_abc123" - } - ], - "get": { - "operationId": "getPod", - "summary": "Get a pod", - "description": "Returns a single pod by ID.", - "tags": [ - "Pods" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Pod" - }, - "examples": { - "pod": { - "summary": "Successful response", - "value": { - "id": "7h9k2m4n6p", - "name": "pytorch-training", - "image": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1", - "args": "", - "disk": 50, - "ports": [ - "8888/http", - "22/tcp" - ], - "env": { - "MODEL_NAME": "llama-3" - }, - "registry": null, - "status": "RUNNING", - "actions": [ - "stop", - "restart", - "terminate" - ], - "mounts": { - "persistent": { - "size": 20, - "path": "/workspace" - } - }, - "gpu": { - "id": "NVIDIA GeForce RTX 4090", - "count": 1 - }, - "cloud": "SECURE", - "dataCenterId": "US-KS-2", - "template": "9x4m2p7v", - "cost": 0.44, - "locked": false, - "globalNetworking": { - "enabled": false - }, - "runtime": { - "uptime": 3600 - }, - "createdAt": "2026-06-01T12:00:00Z", - "startedAt": "2026-06-01T12:02:00Z" - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "403": { - "$ref": "#/components/responses/ForbiddenError" - }, - "404": { - "$ref": "#/components/responses/NotFoundError" - }, - "429": { - "$ref": "#/components/responses/TooManyRequestsError" - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - }, - "patch": { - "operationId": "updatePod", - "summary": "Update a pod", - "description": "Partially updates a pod's configuration. This is a PATCH: only the\nfields present in the body are changed, and omitted fields are left\nuntouched. Use empty values only when you explicitly mean to clear a\nfield (for example, set `registry` to `null` or set `ports` to `[]`).\nSee `UpdatePodRequest` for the full body.\n\nMutable fields: `name`, `image`, `args`, `disk`, `ports`, `env`,\n`registry`, `mounts`, `locked`, and `globalNetworking`. Some changes\napply immediately while others (e.g. `globalNetworking`) take effect\non the pod's next start/restart, as noted on the individual fields.\n\nReturns `200` with the full updated pod.\n", - "tags": [ - "Pods" - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/UpdatePodRequest" - }, - "examples": { - "renamePod": { - "summary": "Rename pod", - "value": { - "name": "renamed-training-pod" - } - } - } - } - } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Pod" - }, - "examples": { - "pod": { - "summary": "Successful response", - "value": { - "id": "7h9k2m4n6p", - "name": "renamed-training-pod", - "image": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1", - "args": "", - "disk": 50, - "ports": [ - "8888/http", - "22/tcp" - ], - "env": { - "MODEL_NAME": "llama-3" - }, - "registry": null, - "status": "RUNNING", - "actions": [ - "stop", - "restart", - "terminate" - ], - "mounts": { - "persistent": { - "size": 20, - "path": "/workspace" - } - }, - "gpu": { - "id": "NVIDIA GeForce RTX 4090", - "count": 1 - }, - "cloud": "SECURE", - "dataCenterId": "US-KS-2", - "template": "9x4m2p7v", - "cost": 0.44, - "locked": false, - "globalNetworking": { - "enabled": false - }, - "runtime": { - "uptime": 3600 - }, - "createdAt": "2026-06-01T12:00:00Z", - "startedAt": "2026-06-01T12:02:00Z" - } - } - } - } - } - }, - "400": { - "$ref": "#/components/responses/BadRequestError" - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "403": { - "$ref": "#/components/responses/ForbiddenError" - }, - "404": { - "$ref": "#/components/responses/NotFoundError" - }, - "422": { - "$ref": "#/components/responses/UnprocessableEntityError" - }, - "429": { - "$ref": "#/components/responses/TooManyRequestsError" - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - }, - "delete": { - "operationId": "deletePod", - "summary": "Terminate a pod", - "description": "Permanently terminates and deletes a pod. This is irreversible:\ncompute is released, any `mounts.persistent` host-local storage is\ndestroyed with it (a `mounts.network` volume is only detached — the\nvolume itself is not deleted), and the pod no longer appears in\n`listPods`.\n", - "tags": [ - "Pods" - ], - "responses": { - "204": { - "description": "Deleted. Response has no body." - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "403": { - "$ref": "#/components/responses/ForbiddenError" - }, - "404": { - "$ref": "#/components/responses/NotFoundError" - }, - "429": { - "$ref": "#/components/responses/TooManyRequestsError" - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - } - }, - "/v2/pods/{id}/logs": { - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - }, - "description": "Pod identifier", - "example": "pod_abc123" - } - ], - "get": { - "operationId": "getPodLogs", - "summary": "Stream pod logs", - "description": "Streams pod logs as Server-Sent Events. The `source` query parameter\nselects which log source to include.\n\nThe SSE `data` payload shape is:\n`{ \"source\": \"container\", \"line\": \"...\", \"ts\": \"...\" }`.\nLog-event `id` values are the event `ts` timestamp so\nbrowser/EventSource reconnects can resume with `Last-Event-ID`.\n", - "tags": [ - "Pods" - ], - "parameters": [ - { - "$ref": "#/components/parameters/LogSourceParam" - }, - { - "$ref": "#/components/parameters/LogTail" - }, - { - "$ref": "#/components/parameters/LogSince" - }, - { - "$ref": "#/components/parameters/LogLastEventID" - } - ], - "responses": { - "200": { - "description": "Pod log event stream", - "headers": { - "Cache-Control": { - "schema": { - "type": "string" - }, - "description": "Always `no-cache` for SSE responses." - }, - "Connection": { - "schema": { - "type": "string" - }, - "description": "Always `keep-alive` to hold the SSE stream open." - }, - "X-Accel-Buffering": { - "schema": { - "type": "string" - }, - "description": "Always `no` to disable proxy buffering of the SSE stream." - } - }, - "content": { - "text/event-stream": { - "schema": { - "type": "string", - "description": "Server-Sent Events stream. Each event includes an `id:` line and a JSON `data:` payload with `source`, `line`, and `ts` fields." - }, - "examples": { - "logLine": { - "summary": "Successful response", - "value": "id: 2026-06-01T12:02:03Z/000000000001\ndata: {\"ts\":\"2026-06-01T12:02:03Z\",\"source\":\"container\",\"line\":\"Model loaded.\"}\n" - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "403": { - "$ref": "#/components/responses/ForbiddenError" - }, - "404": { - "$ref": "#/components/responses/NotFoundError" - }, - "429": { - "$ref": "#/components/responses/TooManyRequestsError" - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - } - }, - "/v2/pods/{id}/action": { - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - }, - "example": "pod_abc123" - } - ], - "post": { - "operationId": "podAction", - "summary": "Trigger a pod state transition", - "description": "Triggers a state transition on a pod. Send a JSON body with a single\n`action` field, e.g. `{ \"action\": \"stop\" }`.\n\nValid actions:\n- `start` — boot a stopped pod (`EXITED` or `ERROR`) back toward\n `RUNNING`.\n- `stop` — stop a running or provisioning pod, releasing GPU/CPU\n compute while keeping its disk. The pod moves to `EXITED`.\n- `restart` — restart a `RUNNING` pod's container in place.\n- `terminate` — permanently delete the pod and release its resources\n (equivalent to `deletePod`).\n\nWhich actions are valid depends on the pod's current status, and the\ncurrently permitted set is published in the pod's `actions` field:\n`RUNNING` allows `stop`/`restart`/`terminate`; `EXITED` and `ERROR`\nallow `start`/`terminate`; `PROVISIONING` and `STARTING` allow\n`stop`/`terminate`.\n\n`start`, `stop`, and `restart` return `200` with the updated pod.\n`terminate` returns `204` with no body. Requesting an action that is\nnot valid for the pod's current status returns `409`.\n", - "tags": [ - "Pods" - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/PodActionRequest" - }, - "examples": { - "startPod": { - "summary": "Start pod", - "value": { - "action": "start" - } - } - } - } - } - }, - "responses": { - "200": { - "description": "Action applied — returns updated pod", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Pod" - }, - "examples": { - "pod": { - "summary": "Successful response", - "value": { - "id": "7h9k2m4n6p", - "name": "pytorch-training", - "image": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1", - "args": "", - "disk": 50, - "ports": [ - "8888/http", - "22/tcp" - ], - "env": { - "MODEL_NAME": "llama-3" - }, - "registry": null, - "status": "RUNNING", - "actions": [ - "stop", - "restart", - "terminate" - ], - "mounts": { - "persistent": { - "size": 20, - "path": "/workspace" - } - }, - "gpu": { - "id": "NVIDIA GeForce RTX 4090", - "count": 1 - }, - "cloud": "SECURE", - "dataCenterId": "US-KS-2", - "template": "9x4m2p7v", - "cost": 0.44, - "locked": false, - "globalNetworking": { - "enabled": false - }, - "runtime": { - "uptime": 3600 - }, - "createdAt": "2026-06-01T12:00:00Z", - "startedAt": "2026-06-01T12:02:00Z" - } - } - } - } - } - }, - "204": { - "description": "Only returned when `action=terminate`; response has no body." - }, - "400": { - "$ref": "#/components/responses/BadRequestError" - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "403": { - "$ref": "#/components/responses/ForbiddenError" - }, - "404": { - "$ref": "#/components/responses/NotFoundError" - }, - "409": { - "description": "Action not valid for current pod status", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "422": { - "$ref": "#/components/responses/UnprocessableEntityError" - }, - "429": { - "$ref": "#/components/responses/TooManyRequestsError" - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - } - }, - "/v2/serverless": { - "get": { - "operationId": "listEndpoints", - "summary": "List serverless endpoints", - "description": "Returns all serverless endpoints owned by the authenticated user.", - "tags": [ - "Serverless" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ListEndpointsResponse" - }, - "examples": { - "endpoints": { - "summary": "Successful response", - "value": { - "endpoints": [ - { - "id": "4m7x2k9q", - "name": "image-generator", - "type": "QUEUE_BASED", - "requestUrls": { - "run": "https://api.runpod.ai/v2/4m7x2k9q/run", - "runSync": "https://api.runpod.ai/v2/4m7x2k9q/runsync" - }, - "image": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1", - "args": "", - "disk": 20, - "ports": [ - "8000/http" - ], - "env": { - "MODEL_NAME": "sdxl" - }, - "registry": null, - "gpu": { - "pools": [ - "ADA_24" - ], - "count": 1 - }, - "workers": { - "min": 0, - "max": 5 - }, - "scaling": { - "type": "QUEUE_DELAY", - "value": 4, - "idleTimeout": 5 - }, - "dataCenterIds": [ - "US-KS-2" - ], - "networkVolumes": [ - "2q9m7x4c" - ], - "timeout": 300000, - "flashboot": "OFF", - "createdAt": "2026-06-01T12:00:00Z" - } - ] - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "403": { - "$ref": "#/components/responses/ForbiddenError" - }, - "429": { - "$ref": "#/components/responses/TooManyRequestsError" - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - }, - "post": { - "operationId": "createEndpoint", - "summary": "Create a serverless endpoint", - "description": "Creates a serverless endpoint. Specify `gpu` for compute (CPU\nserverless endpoints are read-only). Container settings can be spread\nfrom a template response — see `CreateEndpointRequest` for the full\nbody.\n\nReturns `201` with the created endpoint. The endpoint can accept jobs\nimmediately, but starts with no active workers unless `workers.min`\nis greater than 0. Workers are provisioned on demand and autoscaled\nbetween `workers.min` and `workers.max` according to the `scaling`\npolicy, so the first request to an idle endpoint may incur cold-start\nlatency while a worker pulls its image and boots.\n", - "tags": [ - "Serverless" - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CreateEndpointRequest" - }, - "examples": { - "serverlessEndpoint": { - "summary": "Serverless endpoint", - "value": { - "name": "image-generator", - "image": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1", - "gpu": { - "pools": [ - "ADA_24" - ], - "count": 1 - }, - "workers": { - "min": 0, - "max": 5 - }, - "scaling": { - "type": "QUEUE_DELAY", - "value": 4, - "idleTimeout": 5 - }, - "dataCenterIds": [ - "US-KS-2" - ], - "timeout": 300000 - } - } - } - } - } - }, - "responses": { - "201": { - "description": "Created", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Endpoint" - }, - "examples": { - "endpoint": { - "summary": "Successful response", - "value": { - "id": "4m7x2k9q", - "name": "image-generator", - "type": "QUEUE_BASED", - "requestUrls": { - "run": "https://api.runpod.ai/v2/4m7x2k9q/run", - "runSync": "https://api.runpod.ai/v2/4m7x2k9q/runsync" - }, - "image": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1", - "args": "", - "disk": 20, - "ports": [ - "8000/http" - ], - "env": { - "MODEL_NAME": "sdxl" - }, - "registry": null, - "gpu": { - "pools": [ - "ADA_24" - ], - "count": 1 - }, - "workers": { - "min": 0, - "max": 5 - }, - "scaling": { - "type": "QUEUE_DELAY", - "value": 4, - "idleTimeout": 5 - }, - "dataCenterIds": [ - "US-KS-2" - ], - "networkVolumes": [ - "2q9m7x4c" - ], - "timeout": 300000, - "flashboot": "OFF", - "createdAt": "2026-06-01T12:00:00Z" - } - } - } - } - } - }, - "400": { - "$ref": "#/components/responses/BadRequestError" - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "403": { - "$ref": "#/components/responses/ForbiddenError" - }, - "422": { - "$ref": "#/components/responses/UnprocessableEntityError" - }, - "429": { - "$ref": "#/components/responses/TooManyRequestsError" - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - } - }, - "/v2/serverless/{id}": { - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - }, - "description": "Serverless endpoint identifier", - "example": "ep_abc123" - } - ], - "get": { - "operationId": "getEndpoint", - "summary": "Get a serverless endpoint", - "description": "Returns a single serverless endpoint by ID.", - "tags": [ - "Serverless" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Endpoint" - }, - "examples": { - "endpoint": { - "summary": "Successful response", - "value": { - "id": "4m7x2k9q", - "name": "image-generator", - "type": "LOAD_BALANCING", - "requestUrls": { - "base": "https://4m7x2k9q.api.runpod.ai" - }, - "image": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1", - "args": "", - "disk": 20, - "ports": [ - "8000/http" - ], - "env": { - "MODEL_NAME": "sdxl" - }, - "registry": null, - "gpu": { - "pools": [ - "ADA_24" - ], - "count": 1 - }, - "workers": { - "min": 0, - "max": 5 - }, - "scaling": { - "type": "QUEUE_DELAY", - "value": 4, - "idleTimeout": 5 - }, - "dataCenterIds": [ - "US-KS-2" - ], - "networkVolumes": [ - "2q9m7x4c" - ], - "timeout": 300000, - "flashboot": "OFF", - "createdAt": "2026-06-01T12:00:00Z" - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "403": { - "$ref": "#/components/responses/ForbiddenError" - }, - "404": { - "$ref": "#/components/responses/NotFoundError" - }, - "429": { - "$ref": "#/components/responses/TooManyRequestsError" - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - }, - "patch": { - "operationId": "updateEndpoint", - "summary": "Update a serverless endpoint", - "description": "Partially updates a serverless endpoint. This is a PATCH: only the\nfields present in the body are changed; omitted fields are left\nuntouched. See `UpdateEndpointRequest` for the full body.\n\nMutable fields: `name`, `gpu`, `workers` (`min`/`max`), `scaling`\n(`type`/`value`/`idleTimeout`), `dataCenterIds`, `networkVolumes`,\n`timeout`, `flashboot`, and the container settings (`image`, `args`,\n`disk`, `ports`, `env`, `registry`).\n\nReturns `200` with the full updated endpoint. Effect timing differs\nby field: scaling and worker-bound settings (`workers`, `scaling`,\n`timeout`) are applied to the autoscaler promptly, while\ncontainer-affecting changes (e.g. `image`, `env`) create a new\nendpoint release that rolls out as workers cycle — in-flight workers\nkeep the previous version until they are replaced. Track rollout via\n`listEndpointReleases`.\n", - "tags": [ - "Serverless" - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/UpdateEndpointRequest" - }, - "examples": { - "scaleEndpoint": { - "summary": "Scale endpoint", - "value": { - "workers": { - "min": 1, - "max": 10 - }, - "scaling": { - "type": "REQUEST_COUNT", - "value": 8, - "idleTimeout": 10 - } - } - } - } - } - } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Endpoint" - }, - "examples": { - "endpoint": { - "summary": "Successful response", - "value": { - "id": "4m7x2k9q", - "name": "image-generator", - "type": "QUEUE_BASED", - "requestUrls": { - "run": "https://api.runpod.ai/v2/4m7x2k9q/run", - "runSync": "https://api.runpod.ai/v2/4m7x2k9q/runsync" - }, - "image": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1", - "args": "", - "disk": 20, - "ports": [ - "8000/http" - ], - "env": { - "MODEL_NAME": "sdxl" - }, - "registry": null, - "gpu": { - "pools": [ - "ADA_24" - ], - "count": 1 - }, - "workers": { - "min": 1, - "max": 10 - }, - "scaling": { - "type": "REQUEST_COUNT", - "value": 8, - "idleTimeout": 10 - }, - "dataCenterIds": [ - "US-KS-2" - ], - "networkVolumes": [ - "2q9m7x4c" - ], - "timeout": 300000, - "flashboot": "OFF", - "createdAt": "2026-06-01T12:00:00Z" - } - } - } - } - } - }, - "400": { - "$ref": "#/components/responses/BadRequestError" - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "403": { - "$ref": "#/components/responses/ForbiddenError" - }, - "404": { - "$ref": "#/components/responses/NotFoundError" - }, - "422": { - "$ref": "#/components/responses/UnprocessableEntityError" - }, - "429": { - "$ref": "#/components/responses/TooManyRequestsError" - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - }, - "delete": { - "operationId": "deleteEndpoint", - "summary": "Delete a serverless endpoint", - "description": "Permanently deletes a serverless endpoint and its bound template.\nThis is irreversible: all workers are terminated and any queued or\nin-progress jobs are cancelled.\n", - "tags": [ - "Serverless" - ], - "responses": { - "204": { - "description": "Deleted. Response has no body." - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "403": { - "$ref": "#/components/responses/ForbiddenError" - }, - "404": { - "$ref": "#/components/responses/NotFoundError" - }, - "429": { - "$ref": "#/components/responses/TooManyRequestsError" - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - } - }, - "/v2/serverless/{id}/workers": { - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - }, - "description": "Serverless endpoint identifier", - "example": "ep_abc123" - } - ], - "get": { - "operationId": "listEndpointWorkers", - "summary": "List serverless endpoint workers", - "description": "Lists the active workers for a serverless endpoint.\n\n**Returns.** A `200` with a `ListEndpointWorkersResponse`: a\n`workers` array (one entry per active worker, each carrying its `id`,\n`status`, and runtime details) plus a `summary` of worker counts\ngrouped by status. Only currently active workers are included;\nscaled-down workers are not returned.\n\n**How `status` is determined.** Each worker's `status` is derived by\nreconciling the worker pod's lifecycle status with the endpoint's\nlive job-queue view (which workers are actively serving requests).\nWhen the job-queue view is unavailable, the response degrades\ngracefully: the shape is unchanged, but each `status` and the summary\ncounts fall back to pod lifecycle alone.\n", - "tags": [ - "Serverless" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ListEndpointWorkersResponse" - }, - "examples": { - "workers": { - "summary": "Successful response", - "value": { - "endpointVersion": 4, - "summary": { - "running": 1, - "idle": 1, - "initializing": 0, - "throttled": 0, - "unhealthy": 0, - "total": 2 - }, - "workers": [ - { - "id": "8g3n5t6r", - "status": "RUNNING", - "isStale": false, - "version": 4, - "gpuCount": 1, - "image": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1", - "uptimeSeconds": 3600, - "gpuTypeId": "NVIDIA GeForce RTX 4090", - "dataCenterId": "US-KS-2", - "startedAt": "2026-06-01T12:05:00Z" - } - ] - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "403": { - "$ref": "#/components/responses/ForbiddenError" - }, - "404": { - "$ref": "#/components/responses/NotFoundError" - }, - "429": { - "$ref": "#/components/responses/TooManyRequestsError" - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - } - }, - "/v2/serverless/{id}/releases": { - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - }, - "description": "Serverless endpoint identifier", - "example": "ep_abc123" - } - ], - "get": { - "operationId": "listEndpointReleases", - "summary": "List serverless endpoint releases", - "description": "Returns the endpoint's release history (newest first) plus a rollout\nsummary of how many workers are running the current version. Each\nrelease is a versioned configuration snapshot with a `diff` of what\nchanged; build-driven releases carry a `buildId` (fetch build detail via\nthe builds sub-routes).\n", - "tags": [ - "Serverless" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ListEndpointReleasesResponse" - }, - "examples": { - "releases": { - "summary": "Successful response", - "value": { - "endpointVersion": 4, - "rollout": { - "inProgress": true, - "workersOnLatest": 1, - "workersTotal": 2, - "percentOnLatest": 50 - }, - "releases": [ - { - "id": "5r9x2m7q", - "version": 4, - "source": "MANUAL", - "buildId": null, - "createdByUserId": null, - "workerCount": 2, - "createdAt": "2026-06-01T12:10:00Z", - "diff": [ - { - "field": "workers.max", - "old": 5, - "new": 10 - } - ] - } - ] - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "403": { - "$ref": "#/components/responses/ForbiddenError" - }, - "404": { - "$ref": "#/components/responses/NotFoundError" - }, - "429": { - "$ref": "#/components/responses/TooManyRequestsError" - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - } - }, - "/v2/serverless/{id}/workers/{workerId}/logs": { - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - }, - "description": "Serverless endpoint identifier", - "example": "ep_abc123" - }, - { - "name": "workerId", - "in": "path", - "required": true, - "schema": { - "type": "string" - }, - "description": "Worker identifier (from GET /v2/serverless/{id}/workers)", - "example": "worker_abc" - } - ], - "get": { - "operationId": "getWorkerLogs", - "summary": "Stream serverless worker logs", - "description": "Streams a serverless worker's logs as Server-Sent Events. The `source`\nquery parameter selects which log source to include.\n\nThe SSE `data` payload shape is:\n`{ \"source\": \"container\", \"line\": \"...\", \"ts\": \"...\" }`.\nLog-event `id` values are the event `ts` timestamp so browser/EventSource\nreconnects can resume with `Last-Event-ID`.\n", - "tags": [ - "Serverless" - ], - "parameters": [ - { - "$ref": "#/components/parameters/LogSourceParam" - }, - { - "$ref": "#/components/parameters/LogTail" - }, - { - "$ref": "#/components/parameters/LogSince" - }, - { - "$ref": "#/components/parameters/LogLastEventID" - } - ], - "responses": { - "200": { - "description": "Worker log event stream", - "headers": { - "Cache-Control": { - "schema": { - "type": "string" - }, - "description": "Always `no-cache` for SSE responses." - }, - "Connection": { - "schema": { - "type": "string" - }, - "description": "Always `keep-alive` to hold the SSE stream open." - }, - "X-Accel-Buffering": { - "schema": { - "type": "string" - }, - "description": "Always `no` to disable proxy buffering of the SSE stream." - } - }, - "content": { - "text/event-stream": { - "schema": { - "type": "string", - "description": "Server-Sent Events stream. Each event includes an `id:` line and a JSON `data:` payload with `source`, `line`, and `ts` fields." - }, - "examples": { - "logLine": { - "summary": "Successful response", - "value": "id: 2026-06-01T12:05:04Z/000000000042\ndata: {\"ts\":\"2026-06-01T12:05:04Z\",\"source\":\"container\",\"line\":\"Worker ready.\"}\n" - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "403": { - "$ref": "#/components/responses/ForbiddenError" - }, - "404": { - "$ref": "#/components/responses/NotFoundError" - }, - "429": { - "$ref": "#/components/responses/TooManyRequestsError" - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - } - }, - "/v2/templates": { - "get": { - "operationId": "listTemplates", - "summary": "List templates", - "description": "Returns all templates owned by the authenticated user.", - "tags": [ - "Templates" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ListTemplatesResponse" - }, - "examples": { - "templates": { - "summary": "Successful response", - "value": { - "templates": [ - { - "id": "9x4m2p7v", - "name": "PyTorch GPU Template", - "image": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1", - "args": "", - "disk": 50, - "mounts": { - "persistent": { - "size": 20, - "path": "/workspace" - } - }, - "ports": [ - "8888/http" - ], - "env": { - "JUPYTER_ENABLE_LAB": "yes" - }, - "registry": null, - "serverless": false, - "public": false, - "category": "NVIDIA" - } - ] - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "403": { - "$ref": "#/components/responses/ForbiddenError" - }, - "429": { - "$ref": "#/components/responses/TooManyRequestsError" - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - }, - "post": { - "operationId": "createTemplate", - "summary": "Create a template", - "description": "Creates a reusable container-configuration preset — image, disk,\nports, env, registry, and mount settings — for pods and serverless\nendpoints. `createPod` and `createEndpoint` don't take a template ID;\ninstead, spread a template's fields into the request body directly.\nReturns the created template.\n", - "tags": [ - "Templates" - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CreateTemplateRequest" - }, - "examples": { - "podTemplate": { - "summary": "Pod template", - "value": { - "name": "PyTorch GPU Template", - "image": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1", - "category": "NVIDIA", - "disk": 50, - "ports": [ - "8888/http" - ], - "env": { - "JUPYTER_ENABLE_LAB": "yes" - }, - "mounts": { - "persistent": { - "size": 20, - "path": "/workspace" - } - }, - "serverless": false, - "public": false - } - } - } - } - } - }, - "responses": { - "201": { - "description": "Created", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Template" - }, - "examples": { - "template": { - "summary": "Successful response", - "value": { - "id": "9x4m2p7v", - "name": "PyTorch GPU Template", - "image": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1", - "args": "", - "disk": 50, - "mounts": { - "persistent": { - "size": 20, - "path": "/workspace" - } - }, - "ports": [ - "8888/http" - ], - "env": { - "JUPYTER_ENABLE_LAB": "yes" - }, - "registry": null, - "serverless": false, - "public": false, - "category": "NVIDIA" - } - } - } - } - } - }, - "400": { - "$ref": "#/components/responses/BadRequestError" - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "403": { - "$ref": "#/components/responses/ForbiddenError" - }, - "422": { - "$ref": "#/components/responses/UnprocessableEntityError" - }, - "429": { - "$ref": "#/components/responses/TooManyRequestsError" - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - } - }, - "/v2/templates/{id}": { - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - }, - "example": "tpl_abc" - } - ], - "get": { - "operationId": "getTemplate", - "summary": "Get a template", - "description": "Returns the full configuration of a single template by ID.", - "tags": [ - "Templates" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Template" - }, - "examples": { - "template": { - "summary": "Successful response", - "value": { - "id": "9x4m2p7v", - "name": "PyTorch GPU Template", - "image": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1", - "args": "", - "disk": 50, - "mounts": { - "persistent": { - "size": 20, - "path": "/workspace" - } - }, - "ports": [ - "8888/http" - ], - "env": { - "JUPYTER_ENABLE_LAB": "yes" - }, - "registry": null, - "serverless": false, - "public": false, - "category": "NVIDIA" - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "403": { - "$ref": "#/components/responses/ForbiddenError" - }, - "404": { - "$ref": "#/components/responses/NotFoundError" - }, - "429": { - "$ref": "#/components/responses/TooManyRequestsError" - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - }, - "patch": { - "operationId": "updateTemplate", - "summary": "Update a template", - "description": "Partially updates a template. This is a PATCH: only the fields\npresent in the body are changed; omitted fields are left untouched.\nSee `UpdateTemplateRequest` for the full body.\n\nMutable fields: `name`, `image`, `args`, `disk`, `ports`, `env`,\n`registry`, `mounts`, `serverless`, `public`, and `category`.\n\nOnly the template's owner can update it (authenticated via the\nrequest's API key); other users' templates are neither visible nor\nmutable. Returns `200` with the full updated template. Pods and\nendpoints already created from this template are not changed\nretroactively — the template is a snapshot applied at creation time.\n", - "tags": [ - "Templates" - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/UpdateTemplateRequest" - }, - "examples": { - "renameTemplate": { - "summary": "Rename template", - "value": { - "name": "Renamed PyTorch Template" - } - } - } - } - } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Template" - }, - "examples": { - "template": { - "summary": "Successful response", - "value": { - "id": "9x4m2p7v", - "name": "Renamed PyTorch Template", - "image": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1", - "args": "", - "disk": 50, - "mounts": { - "persistent": { - "size": 20, - "path": "/workspace" - } - }, - "ports": [ - "8888/http" - ], - "env": { - "JUPYTER_ENABLE_LAB": "yes" - }, - "registry": null, - "serverless": false, - "public": false, - "category": "NVIDIA" - } - } - } - } - } - }, - "400": { - "$ref": "#/components/responses/BadRequestError" - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "403": { - "$ref": "#/components/responses/ForbiddenError" - }, - "404": { - "$ref": "#/components/responses/NotFoundError" - }, - "422": { - "$ref": "#/components/responses/UnprocessableEntityError" - }, - "429": { - "$ref": "#/components/responses/TooManyRequestsError" - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - }, - "delete": { - "operationId": "deleteTemplate", - "summary": "Delete a template", - "description": "Permanently deletes a template by ID. Rejected if the template is\ncurrently referenced by a pod (see that pod's `template` field) or\nbound to a serverless endpoint.\n", - "tags": [ - "Templates" - ], - "responses": { - "204": { - "description": "Deleted. Response has no body." - }, - "400": { - "description": "Template is in use by a pod or serverless endpoint and cannot be deleted", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "403": { - "$ref": "#/components/responses/ForbiddenError" - }, - "404": { - "$ref": "#/components/responses/NotFoundError" - }, - "429": { - "$ref": "#/components/responses/TooManyRequestsError" - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - } - }, - "/v2/network-volumes": { - "get": { - "operationId": "listNetworkVolumes", - "summary": "List network volumes", - "description": "Returns all network volumes owned by the authenticated user.", - "tags": [ - "Network Volumes" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ListNetworkVolumesResponse" - }, - "examples": { - "networkVolumes": { - "summary": "Successful response", - "value": { - "networkVolumes": [ - { - "id": "2q9m7x4c", - "name": "training-dataset", - "size": 100, - "dataCenter": "US-KS-2", - "type": "HIGH_PERFORMANCE" - } - ] - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "403": { - "$ref": "#/components/responses/ForbiddenError" - }, - "429": { - "$ref": "#/components/responses/TooManyRequestsError" - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - }, - "post": { - "operationId": "createNetworkVolume", - "summary": "Create a network volume", - "description": "Provisions a new network volume — persistent, network-attached\nstorage that can be mounted into pods and serverless workers.\nRequired inputs are `name`, `size` (in GB), and `dataCenter`; an\noptional `type` selects the storage tier and is immutable after\ncreation. See `CreateNetworkVolumeRequest` for the size bounds and\ntier options.\n\nThis creates a billable persistent resource that keeps incurring\nstorage charges until it is deleted. Returns `201` with the created\nnetwork volume, including its assigned `id`.\n", - "tags": [ - "Network Volumes" - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CreateNetworkVolumeRequest" - }, - "examples": { - "networkVolume": { - "summary": "Network volume", - "value": { - "name": "training-dataset", - "dataCenter": "US-KS-2", - "size": 50, - "type": "HIGH_PERFORMANCE" - } - } - } - } - } - }, - "responses": { - "201": { - "description": "Created", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/NetworkVolume" - }, - "examples": { - "networkVolume": { - "summary": "Successful response", - "value": { - "id": "2q9m7x4c", - "name": "training-dataset", - "size": 50, - "dataCenter": "US-KS-2", - "type": "HIGH_PERFORMANCE" - } - } - } - } - } - }, - "400": { - "$ref": "#/components/responses/BadRequestError" - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "403": { - "$ref": "#/components/responses/ForbiddenError" - }, - "422": { - "$ref": "#/components/responses/UnprocessableEntityError" - }, - "429": { - "$ref": "#/components/responses/TooManyRequestsError" - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - } - }, - "/v2/network-volumes/{id}": { - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - }, - "description": "Network volume identifier", - "example": "agv6w2qcg7" - } - ], - "get": { - "operationId": "getNetworkVolume", - "summary": "Get a network volume", - "description": "Returns a single network volume by ID.", - "tags": [ - "Network Volumes" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/NetworkVolume" - }, - "examples": { - "networkVolume": { - "summary": "Successful response", - "value": { - "id": "2q9m7x4c", - "name": "training-dataset", - "size": 100, - "dataCenter": "US-KS-2", - "type": "HIGH_PERFORMANCE" - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "403": { - "$ref": "#/components/responses/ForbiddenError" - }, - "404": { - "$ref": "#/components/responses/NotFoundError" - }, - "429": { - "$ref": "#/components/responses/TooManyRequestsError" - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - }, - "patch": { - "operationId": "updateNetworkVolume", - "summary": "Update a network volume", - "description": "Updates mutable fields on a network volume. Only provided fields are changed.\nNote: `size` may only increase; attempts to reduce size will be rejected.\n", - "tags": [ - "Network Volumes" - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/UpdateNetworkVolumeRequest" - }, - "examples": { - "resizeNetworkVolume": { - "summary": "Resize network volume", - "value": { - "size": 200 - } - } - } - } - } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/NetworkVolume" - }, - "examples": { - "networkVolume": { - "summary": "Successful response", - "value": { - "id": "2q9m7x4c", - "name": "training-dataset", - "size": 200, - "dataCenter": "US-KS-2", - "type": "HIGH_PERFORMANCE" - } - } - } - } - } - }, - "400": { - "description": "Invalid request body or size decrease attempted", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "403": { - "$ref": "#/components/responses/ForbiddenError" - }, - "404": { - "$ref": "#/components/responses/NotFoundError" - }, - "422": { - "$ref": "#/components/responses/UnprocessableEntityError" - }, - "429": { - "$ref": "#/components/responses/TooManyRequestsError" - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - }, - "delete": { - "operationId": "deleteNetworkVolume", - "summary": "Delete a network volume", - "description": "Permanently deletes a network volume and releases its storage.", - "tags": [ - "Network Volumes" - ], - "responses": { - "204": { - "description": "Deleted. Response has no body." - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "403": { - "$ref": "#/components/responses/ForbiddenError" - }, - "404": { - "$ref": "#/components/responses/NotFoundError" - }, - "429": { - "$ref": "#/components/responses/TooManyRequestsError" - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - } - }, - "/v2/registries": { - "get": { - "operationId": "listRegistries", - "summary": "List container registries", - "description": "Returns all container registry credentials owned by the authenticated user.", - "tags": [ - "Registries" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ListRegistriesResponse" - }, - "examples": { - "registries": { - "summary": "Successful response", - "value": { - "registries": [ - { - "id": "6n2k8v4d", - "name": "dockerhub-private" - } - ] - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "403": { - "$ref": "#/components/responses/ForbiddenError" - }, - "429": { - "$ref": "#/components/responses/TooManyRequestsError" - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - }, - "post": { - "operationId": "createRegistry", - "summary": "Create a container registry credential", - "description": "Stores credentials for a private container registry. Credentials are write-only.", - "tags": [ - "Registries" - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CreateRegistryRequest" - }, - "examples": { - "dockerHubRegistry": { - "summary": "Docker Hub registry", - "value": { - "name": "dockerhub-private", - "username": "runpod-user", - "password": "correct-horse-battery-staple" - } - } - } - } - } - }, - "responses": { - "201": { - "description": "Created", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Registry" - }, - "examples": { - "registry": { - "summary": "Successful response", - "value": { - "id": "6n2k8v4d", - "name": "dockerhub-private" - } - } - } - } - } - }, - "400": { - "$ref": "#/components/responses/BadRequestError" - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "403": { - "$ref": "#/components/responses/ForbiddenError" - }, - "422": { - "$ref": "#/components/responses/UnprocessableEntityError" - }, - "429": { - "$ref": "#/components/responses/TooManyRequestsError" - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - } - }, - "/v2/registries/{id}": { - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - }, - "example": "reg_abc" - } - ], - "get": { - "operationId": "getRegistry", - "summary": "Get a container registry credential", - "description": "Returns a single container registry credential by ID. `username` and\n`password` are never included in the response — credentials are\nwrite-only, matching `createRegistry`.\n", - "tags": [ - "Registries" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Registry" - }, - "examples": { - "registry": { - "summary": "Successful response", - "value": { - "id": "6n2k8v4d", - "name": "dockerhub-private" - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "403": { - "$ref": "#/components/responses/ForbiddenError" - }, - "404": { - "$ref": "#/components/responses/NotFoundError" - }, - "429": { - "$ref": "#/components/responses/TooManyRequestsError" - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - }, - "delete": { - "operationId": "deleteRegistry", - "summary": "Delete a container registry credential", - "description": "Permanently deletes a container registry credential by ID. Rejected\nif any pod currently uses this credential to pull its image.\nTemplates that reference it are not part of that check — they\nsilently lose the reference (`registry` becomes null) instead of\nblocking the delete.\n", - "tags": [ - "Registries" - ], - "responses": { - "204": { - "description": "Deleted. Response has no body." - }, - "400": { - "description": "Registry credential is in use by a pod and cannot be deleted", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "403": { - "$ref": "#/components/responses/ForbiddenError" - }, - "404": { - "$ref": "#/components/responses/NotFoundError" - }, - "429": { - "$ref": "#/components/responses/TooManyRequestsError" - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - } - }, - "/v2/registries/delegations": { - "get": { - "operationId": "listDelegations", - "summary": "List all ECR delegations", - "tags": [ - "Registries" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ListDelegationsResponse" - } - } - } - }, - "429": { - "$ref": "#/components/responses/TooManyRequestsError" - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - }, - "post": { - "operationId": "createDelegation", - "summary": "Register an ECR delegation", - "tags": [ - "Registries" - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CreateDelegationRequest" - } - } - } - }, - "responses": { - "201": { - "description": "Delegation created", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/EcrDelegation" - } - } - } - }, - "429": { - "$ref": "#/components/responses/TooManyRequestsError" - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - } - }, - "/v2/registries/delegations/{id}": { - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - }, - "example": "deleg_abc" - } - ], - "delete": { - "operationId": "revokeDelegation", - "summary": "Revoke an ECR delegation", - "tags": [ - "Registries" - ], - "responses": { - "204": { - "description": "Delegation revoked" - }, - "404": { - "description": "Delegation not found", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "429": { - "$ref": "#/components/responses/TooManyRequestsError" - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - } - }, - "/v2/catalog/gpus": { - "get": { - "operationId": "listGpuTypes", - "summary": "List GPU types", - "description": "Returns available GPU types with pricing. Availability is included only when requested with include=AVAILABILITY.", - "tags": [ - "Catalog" - ], - "parameters": [ - { - "$ref": "#/components/parameters/CatalogIncludeParam" - }, - { - "$ref": "#/components/parameters/GpuProductFilter" - }, - { - "$ref": "#/components/parameters/GpuCountFilter" - }, - { - "$ref": "#/components/parameters/GpuCloudFilter" - }, - { - "$ref": "#/components/parameters/MinCudaVersionFilter" - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ListGpuTypesResponse" - }, - "examples": { - "gpus": { - "summary": "Successful response", - "value": { - "gpus": [ - { - "id": "NVIDIA GeForce RTX 4090", - "name": "RTX 4090", - "pool": "ADA_24", - "manufacturer": "NVIDIA", - "memory": 24, - "secure": true, - "community": true, - "price": { - "secure": 0.44, - "community": 0.31 - }, - "maxCount": { - "secure": 8, - "community": 4 - }, - "availability": "HIGH", - "dataCenters": [ - { - "id": "US-KS-2", - "name": "US Kansas 2", - "availability": "HIGH" - } - ] - } - ] - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "403": { - "$ref": "#/components/responses/ForbiddenError" - }, - "429": { - "$ref": "#/components/responses/TooManyRequestsError" - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - } - }, - "/v2/catalog/gpus/{id}": { - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - }, - "example": "NVIDIA GeForce RTX 4090" - } - ], - "get": { - "operationId": "getGpuType", - "summary": "Get a GPU type", - "description": "Returns a single GPU type with pricing. Availability details are included only when requested with include=AVAILABILITY.", - "tags": [ - "Catalog" - ], - "parameters": [ - { - "$ref": "#/components/parameters/CatalogIncludeParam" - }, - { - "$ref": "#/components/parameters/GpuProductFilter" - }, - { - "$ref": "#/components/parameters/GpuCountFilter" - }, - { - "$ref": "#/components/parameters/GpuCloudFilter" - }, - { - "$ref": "#/components/parameters/MinCudaVersionFilter" - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/GpuType" - }, - "examples": { - "gpu": { - "summary": "Successful response", - "value": { - "id": "NVIDIA GeForce RTX 4090", - "name": "RTX 4090", - "pool": "ADA_24", - "manufacturer": "NVIDIA", - "memory": 24, - "secure": true, - "community": true, - "price": { - "secure": 0.44, - "community": 0.31 - }, - "maxCount": { - "secure": 8, - "community": 4 - }, - "availability": "HIGH", - "dataCenters": [ - { - "id": "US-KS-2", - "name": "US Kansas 2", - "availability": "HIGH" - } - ] - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "403": { - "$ref": "#/components/responses/ForbiddenError" - }, - "404": { - "$ref": "#/components/responses/NotFoundError" - }, - "429": { - "$ref": "#/components/responses/TooManyRequestsError" - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - } - }, - "/v2/catalog/cpus": { - "get": { - "operationId": "listCpuTypes", - "summary": "List CPU types", - "description": "Returns available CPU flavors. Availability is included only when requested with include=AVAILABILITY.", - "tags": [ - "Catalog" - ], - "parameters": [ - { - "$ref": "#/components/parameters/CatalogIncludeParam" - }, - { - "$ref": "#/components/parameters/CpuProductFilter" - }, - { - "$ref": "#/components/parameters/CpuVCPUCountFilter" - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ListCpuTypesResponse" - }, - "examples": { - "cpus": { - "summary": "Successful response", - "value": { - "cpus": [ - { - "id": "cpu3c-2-4", - "name": "Compute-Optimized", - "group": "Gen 3", - "vcpu": { - "min": 2, - "max": 32 - }, - "ramGbPerVcpu": 2.5, - "price": { - "securePerVcpu": 0.04, - "serverlessPerVcpu": 0.03 - }, - "availability": "MEDIUM", - "dataCenters": [ - { - "id": "US-KS-2", - "name": "US Kansas 2", - "availability": "MEDIUM" - } - ] - } - ] - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "403": { - "$ref": "#/components/responses/ForbiddenError" - }, - "429": { - "$ref": "#/components/responses/TooManyRequestsError" - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - } - }, - "/v2/catalog/cpus/{id}": { - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - }, - "example": "cpu5c" - } - ], - "get": { - "operationId": "getCpuType", - "summary": "Get a CPU type", - "description": "Returns a single CPU type with pricing. Availability details are included only when requested with include=AVAILABILITY.", - "tags": [ - "Catalog" - ], - "parameters": [ - { - "$ref": "#/components/parameters/CatalogIncludeParam" - }, - { - "$ref": "#/components/parameters/CpuProductFilter" - }, - { - "$ref": "#/components/parameters/CpuVCPUCountFilter" - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CpuType" - }, - "examples": { - "cpu": { - "summary": "Successful response", - "value": { - "id": "cpu3c-2-4", - "name": "Compute-Optimized", - "group": "Gen 3", - "vcpu": { - "min": 2, - "max": 32 - }, - "ramGbPerVcpu": 2.5, - "price": { - "securePerVcpu": 0.04, - "serverlessPerVcpu": 0.03 - }, - "availability": "MEDIUM", - "dataCenters": [ - { - "id": "US-KS-2", - "name": "US Kansas 2", - "availability": "MEDIUM" - } - ] - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "403": { - "$ref": "#/components/responses/ForbiddenError" - }, - "404": { - "$ref": "#/components/responses/NotFoundError" - }, - "429": { - "$ref": "#/components/responses/TooManyRequestsError" - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - } - }, - "/v2/catalog/datacenters": { - "get": { - "operationId": "listDataCenters", - "summary": "List data centers", - "description": "Returns available data center locations with region, compliance, supported network volume tiers, and global networking support. Use include=GPU_AVAILABILITY or include=CPU_AVAILABILITY to add per-resource availability arrays to each data center. The regions, networkVolumeTypes, compliance, and globalNetwork query parameters filter the list before it is returned.\n", - "tags": [ - "Catalog" - ], - "parameters": [ - { - "name": "include", - "in": "query", - "required": false, - "description": "Comma-separated optional expansions. Supported value: GPU_AVAILABILITY, CPU_AVAILABILITY.", - "style": "form", - "explode": false, - "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/DataCenterInclude" - }, - "example": [ - "GPU_AVAILABILITY" - ] - } - }, - { - "name": "regions", - "in": "query", - "required": false, - "description": "Comma-separated DataCenterRegion enum values. Values within this filter use OR semantics. Different filter families combine with AND.", - "style": "form", - "explode": false, - "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/DataCenterRegion" - }, - "example": [ - "EUROPE", - "ASIA" - ] - } - }, - { - "name": "networkVolumeTypes", - "in": "query", - "required": false, - "description": "Comma-separated volume types. Supported values: STANDARD, HIGH_PERFORMANCE. Values within this filter use AND semantics; volumes=STANDARD,HIGH_PERFORMANCE requires both storage types. Different filter families combine with AND.", - "style": "form", - "explode": false, - "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/VolumeType" - }, - "example": [ - "STANDARD", - "HIGH_PERFORMANCE" - ] - } - }, - { - "name": "compliance", - "in": "query", - "required": false, - "description": "Comma-separated Compliance enum values. Values within this filter use AND semantics; compliance=GDPR,SOC_2_TYPE_2 requires both certifications. Different filter families combine with AND.", - "style": "form", - "explode": false, - "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Compliance" - }, - "example": [ - "GDPR", - "SOC_2_TYPE_2" - ] - } - }, - { - "name": "globalNetwork", - "in": "query", - "required": false, - "description": "Filter by global networking support. true returns only data centers that support global networking; false only those that do not. Different filter families combine with AND.", - "schema": { - "type": "boolean" - }, - "example": true - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ListDataCentersResponse" - }, - "examples": { - "dataCenters": { - "summary": "Successful response", - "value": { - "dataCenters": [ - { - "id": "US-KS-2", - "name": "US Kansas 2", - "region": "NORTH_AMERICA", - "globalNetwork": true, - "networkVolumeTypes": [ - "STANDARD", - "HIGH_PERFORMANCE" - ], - "compliance": [ - "SOC_2_TYPE_2", - "ISO_IEC_27001" - ], - "gpuAvailability": [ - { - "id": "NVIDIA GeForce RTX 4090", - "name": "RTX 4090", - "availability": "HIGH" - } - ], - "cpuAvailability": [ - { - "id": "cpu3c-2-4", - "name": "Compute-Optimized", - "availability": "MEDIUM" - } - ] - } - ] - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "403": { - "$ref": "#/components/responses/ForbiddenError" - }, - "429": { - "$ref": "#/components/responses/TooManyRequestsError" - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - } - }, - "/v2/catalog/datacenters/{id}": { - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - }, - "example": "US-CA-2" - } - ], - "get": { - "operationId": "getDataCenter", - "summary": "Get a data center", - "description": "Returns a single data center. Availability is included only when requested with include=GPU_AVAILABILITY or include=CPU_AVAILABILITY.", - "tags": [ - "Catalog" - ], - "parameters": [ - { - "name": "include", - "in": "query", - "required": false, - "description": "Comma-separated optional expansions. Supported value: GPU_AVAILABILITY, CPU_AVAILABILITY.", - "style": "form", - "explode": false, - "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/DataCenterInclude" - }, - "example": [ - "GPU_AVAILABILITY" - ] - } - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/DataCenter" - }, - "examples": { - "dataCenter": { - "summary": "Successful response", - "value": { - "id": "US-KS-2", - "name": "US Kansas 2", - "region": "NORTH_AMERICA", - "globalNetwork": true, - "networkVolumeTypes": [ - "STANDARD", - "HIGH_PERFORMANCE" - ], - "compliance": [ - "SOC_2_TYPE_2", - "ISO_IEC_27001" - ], - "gpuAvailability": [ - { - "id": "NVIDIA GeForce RTX 4090", - "name": "RTX 4090", - "availability": "HIGH" - } - ], - "cpuAvailability": [ - { - "id": "cpu3c-2-4", - "name": "Compute-Optimized", - "availability": "MEDIUM" - } - ] - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "403": { - "$ref": "#/components/responses/ForbiddenError" - }, - "404": { - "$ref": "#/components/responses/NotFoundError" - }, - "429": { - "$ref": "#/components/responses/TooManyRequestsError" - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - } - }, - "/v2/billing": { - "get": { - "operationId": "listBilling", - "summary": "Get aggregated billing history", - "description": "Returns time-bucketed total spend across all billable Runpod resources for the authenticated user. Use startTime/endTime with bucketSize for an explicit range, or lastN with bucketSize for the most recent buckets. Each record reports one bucket's total plus pod, serverless, storage, public endpoint, and Instant Cluster cost components. The metadata block echoes the resolved query window, record count, and totals across all returned buckets.\n", - "tags": [ - "Billing" - ], - "parameters": [ - { - "$ref": "#/components/parameters/BillingStartTime" - }, - { - "$ref": "#/components/parameters/BillingEndTime" - }, - { - "$ref": "#/components/parameters/BillingBucketSize" - }, - { - "$ref": "#/components/parameters/BillingLastN" - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ListBillingResponse" - }, - "examples": { - "billing": { - "summary": "Successful response", - "value": { - "records": [ - { - "startTime": "2026-06-01T00:00:00Z", - "endTime": "2026-06-02T00:00:00Z", - "totalAmount": 42.34, - "podGpuAmount": 18.2, - "podCpuAmount": 0, - "podDiskAmount": 1.1, - "serverlessGpuAmount": 12.6, - "serverlessCpuAmount": 0, - "serverlessDiskAmount": 0.44, - "serverlessFeeAmount": 1.25, - "storageStandardAmount": 0, - "storageHighPerformanceAmount": 2.5, - "endpointAmount": 3.21, - "clusterGpuAmount": 2.5, - "clusterDiskAmount": 0.3, - "clusterNetworkingAmount": 0.24 - } - ], - "metadata": { - "query": { - "startTime": "2026-06-01T00:00:00Z", - "endTime": "2026-06-02T00:00:00Z", - "bucketSize": "day" - }, - "recordCount": 1, - "totals": { - "totalAmount": 42.34, - "podGpuAmount": 18.2, - "podCpuAmount": 0, - "podDiskAmount": 1.1, - "serverlessGpuAmount": 12.6, - "serverlessCpuAmount": 0, - "serverlessDiskAmount": 0.44, - "serverlessFeeAmount": 1.25, - "storageStandardAmount": 0, - "storageHighPerformanceAmount": 2.5, - "endpointAmount": 3.21, - "clusterGpuAmount": 2.5, - "clusterDiskAmount": 0.3, - "clusterNetworkingAmount": 0.24 - } - } - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "403": { - "$ref": "#/components/responses/ForbiddenError" - }, - "429": { - "$ref": "#/components/responses/TooManyRequestsError" - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - } - }, - "/v2/billing/pods": { - "get": { - "operationId": "listPodBilling", - "summary": "Get pod billing history", - "description": "Returns pod-only billing detail for the authenticated user, split into time buckets by startTime/endTime with bucketSize or by lastN recent buckets. Use podId to narrow the response to one GPU or CPU pod; without it, records are emitted per pod per bucket. Each record includes podId, GPU, CPU, disk, and total amounts, while metadata echoes the resolved query and totals across the pod records. Use listBilling when you need aggregate spend across every billable resource family.\n", - "tags": [ - "Billing" - ], - "parameters": [ - { - "$ref": "#/components/parameters/BillingStartTime" - }, - { - "$ref": "#/components/parameters/BillingEndTime" - }, - { - "$ref": "#/components/parameters/BillingBucketSize" - }, - { - "$ref": "#/components/parameters/BillingLastN" - }, - { - "name": "podId", - "in": "query", - "required": false, - "description": "Filter to a specific pod (GPU or CPU).", - "schema": { - "type": "string" - }, - "example": "pod_abc123" - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ListPodBillingResponse" - }, - "examples": { - "podBilling": { - "summary": "Successful response", - "value": { - "records": [ - { - "startTime": "2026-06-01T00:00:00Z", - "endTime": "2026-06-02T00:00:00Z", - "podId": "7h9k2m4n6p", - "totalAmount": 12.34, - "gpuAmount": 11.1, - "cpuAmount": 0, - "diskAmount": 1.24 - } - ], - "metadata": { - "query": { - "startTime": "2026-06-01T00:00:00Z", - "endTime": "2026-06-02T00:00:00Z", - "bucketSize": "day", - "podId": "7h9k2m4n6p" - }, - "recordCount": 1, - "totals": { - "totalAmount": 12.34, - "gpuAmount": 11.1, - "cpuAmount": 0, - "diskAmount": 1.24 - }, - "uniquePodCount": 1 - } - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "403": { - "$ref": "#/components/responses/ForbiddenError" - }, - "429": { - "$ref": "#/components/responses/TooManyRequestsError" - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - } - }, - "/v2/billing/serverless": { - "get": { - "operationId": "listServerlessBilling", - "summary": "Get serverless billing history", - "description": "Returns serverless endpoint billing detail for the authenticated user, split into time buckets by startTime/endTime with bucketSize or by lastN recent buckets. Use serverlessId to filter to one endpoint; without it, records are emitted per serverless endpoint per bucket. Each record reports endpoint-level GPU, CPU, disk, platform fee, and total amounts. This is distinct from pod billing, which covers standalone GPU and CPU pod costs rather than serverless endpoint workloads.\n", - "tags": [ - "Billing" - ], - "parameters": [ - { - "$ref": "#/components/parameters/BillingStartTime" - }, - { - "$ref": "#/components/parameters/BillingEndTime" - }, - { - "$ref": "#/components/parameters/BillingBucketSize" - }, - { - "$ref": "#/components/parameters/BillingLastN" - }, - { - "name": "serverlessId", - "in": "query", - "required": false, - "description": "Filter to a specific serverless endpoint.", - "schema": { - "type": "string" - }, - "example": "jpnw0v75y3qoql" - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ListServerlessBillingResponse" - }, - "examples": { - "serverlessBilling": { - "summary": "Successful response", - "value": { - "records": [ - { - "startTime": "2026-06-01T00:00:00Z", - "endTime": "2026-06-02T00:00:00Z", - "serverlessId": "4m7x2k9q", - "totalAmount": 8.9, - "gpuAmount": 7.5, - "cpuAmount": 0, - "diskAmount": 0.4, - "feeAmount": 1 - } - ], - "metadata": { - "query": { - "startTime": "2026-06-01T00:00:00Z", - "endTime": "2026-06-02T00:00:00Z", - "bucketSize": "day", - "serverlessId": "4m7x2k9q" - }, - "recordCount": 1, - "totals": { - "totalAmount": 8.9, - "gpuAmount": 7.5, - "cpuAmount": 0, - "diskAmount": 0.4, - "feeAmount": 1 - }, - "uniqueServerlessCount": 1 - } - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "403": { - "$ref": "#/components/responses/ForbiddenError" - }, - "429": { - "$ref": "#/components/responses/TooManyRequestsError" - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - } - }, - "/v2/billing/endpoints": { - "get": { - "operationId": "listEndpointBilling", - "summary": "Get public endpoint billing history", - "description": "Returns Runpod public endpoint billing history for the authenticated user, split into time buckets by startTime/endTime with bucketSize or by lastN recent buckets. Each record reports the endpoint total for one bucket, and metadata echoes the resolved query window, record count, and total endpoint amount across all returned records.\n", - "tags": [ - "Billing" - ], - "parameters": [ - { - "$ref": "#/components/parameters/BillingStartTime" - }, - { - "$ref": "#/components/parameters/BillingEndTime" - }, - { - "$ref": "#/components/parameters/BillingBucketSize" - }, - { - "$ref": "#/components/parameters/BillingLastN" - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ListEndpointBillingResponse" - }, - "examples": { - "endpointBilling": { - "summary": "Successful response", - "value": { - "records": [ - { - "startTime": "2026-06-01T00:00:00Z", - "endTime": "2026-06-02T00:00:00Z", - "totalAmount": 3.21 - } - ], - "metadata": { - "query": { - "startTime": "2026-06-01T00:00:00Z", - "endTime": "2026-06-02T00:00:00Z", - "bucketSize": "day" - }, - "recordCount": 1, - "totals": { - "totalAmount": 3.21 - } - } - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "403": { - "$ref": "#/components/responses/ForbiddenError" - }, - "429": { - "$ref": "#/components/responses/TooManyRequestsError" - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - } - }, - "/v2/billing/networkvolumes": { - "get": { - "operationId": "listNetworkVolumeBilling", - "summary": "Get network volume billing history", - "description": "Returns network volume billing history for the authenticated user, split into time buckets by startTime/endTime with bucketSize or by lastN recent buckets. Use networkVolumeId to filter to one volume; without it, records are emitted per volume per bucket. Each record includes standard storage, high-performance storage, and total amounts, while metadata reports the resolved query, distinct volume count, and totals across the returned records.\n", - "tags": [ - "Billing" - ], - "parameters": [ - { - "$ref": "#/components/parameters/BillingStartTime" - }, - { - "$ref": "#/components/parameters/BillingEndTime" - }, - { - "$ref": "#/components/parameters/BillingBucketSize" - }, - { - "$ref": "#/components/parameters/BillingLastN" - }, - { - "name": "networkVolumeId", - "in": "query", - "required": false, - "description": "Filter to a specific network volume.", - "schema": { - "type": "string" - }, - "example": "vol_abc123" - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ListNetworkVolumeBillingResponse" - }, - "examples": { - "networkVolumeBilling": { - "summary": "Successful response", - "value": { - "records": [ - { - "startTime": "2026-06-01T00:00:00Z", - "endTime": "2026-06-02T00:00:00Z", - "networkVolumeId": "2q9m7x4c", - "totalAmount": 5.79, - "standardAmount": 0, - "highPerformanceAmount": 5.79 - } - ], - "metadata": { - "query": { - "startTime": "2026-06-01T00:00:00Z", - "endTime": "2026-06-02T00:00:00Z", - "bucketSize": "day", - "networkVolumeId": "2q9m7x4c" - }, - "recordCount": 1, - "totals": { - "totalAmount": 5.79, - "standardAmount": 0, - "highPerformanceAmount": 5.79 - }, - "uniqueNetworkVolumeCount": 1 - } - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "403": { - "$ref": "#/components/responses/ForbiddenError" - }, - "429": { - "$ref": "#/components/responses/TooManyRequestsError" - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - } - }, - "/v2/billing/clusters": { - "get": { - "operationId": "listClusterBilling", - "summary": "Get Instant Cluster billing history", - "description": "Returns Instant Cluster billing history for the authenticated user, split into time buckets by startTime/endTime with bucketSize or by lastN recent buckets. Use clusterId to filter to one cluster; without it, records are emitted per cluster per bucket. Each record includes GPU compute, disk, inter-node networking, and total amounts. Instant Clusters are GPU-only, so no CPU cost component is returned.\n", - "tags": [ - "Billing" - ], - "parameters": [ - { - "$ref": "#/components/parameters/BillingStartTime" - }, - { - "$ref": "#/components/parameters/BillingEndTime" - }, - { - "$ref": "#/components/parameters/BillingBucketSize" - }, - { - "$ref": "#/components/parameters/BillingLastN" - }, - { - "name": "clusterId", - "in": "query", - "required": false, - "description": "Filter to a specific Instant Cluster.", - "schema": { - "type": "string" - }, - "example": "cluster_abc123" - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ListClusterBillingResponse" - }, - "examples": { - "clusterBilling": { - "summary": "Successful response", - "value": { - "records": [ - { - "startTime": "2026-06-01T00:00:00Z", - "endTime": "2026-06-02T00:00:00Z", - "clusterId": "5c2n8m4q", - "totalAmount": 99, - "gpuAmount": 95, - "diskAmount": 3, - "networkingAmount": 1 - } - ], - "metadata": { - "query": { - "startTime": "2026-06-01T00:00:00Z", - "endTime": "2026-06-02T00:00:00Z", - "bucketSize": "day", - "clusterId": "5c2n8m4q" - }, - "recordCount": 1, - "totals": { - "totalAmount": 99, - "gpuAmount": 95, - "diskAmount": 3, - "networkingAmount": 1 - }, - "uniqueClusterCount": 1 - } - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "403": { - "$ref": "#/components/responses/ForbiddenError" - }, - "429": { - "$ref": "#/components/responses/TooManyRequestsError" - }, - "default": { - "description": "Error", - "content": { - "application/problem+json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - } - } - } -} +--- +title: "API v2" +sidebarTitle: "Overview" +description: "Programmatically manage Runpod resources using the API v2." +--- + + + API v2 is currently in beta. Endpoints and behavior may change before general availability. + + +The Runpod API v2 provides programmatic access to your Runpod resources over standard HTTP. Use it to create and manage Pods, query Serverless endpoints, provision storage, and retrieve billing data — without using the console. + +## Base URL + +``` +https://api.runpod.io/v2 +``` +The Runpod API v2 provides programmatic access to all Runpod compute resources. Integrate GPU infrastructure into your applications, workflows, and automation systems. + +## Available resources + +- **Pods**: Create and manage persistent GPU instances for development, training, and long-running workloads. +- **Serverless**: Deploy and scale containerized applications with autoscaling and job monitoring. +- **Templates**: Save and reuse Pod and endpoint configurations. +- **Network volumes**: Create persistent storage attachable to multiple resources. +- **Container registry auth**: Connect to private Docker registries. +- **Catalog**: Browse available GPU types, CPU types, and data centers. +- **Billing**: Access usage metrics and billing information. + +## Authentication + +All requests require a [Runpod API key](/get-started/api-keys) in the request headers. The API uses standard HTTP methods and returns JSON responses. + +## OpenAPI schema + +Retrieve the complete OpenAPI specification for client generation, request validation, or tooling integration. + + + +```bash cURL +curl --request GET \ + --url https://api.runpod.io/v2/openapi.json \ + --header 'Authorization: Bearer RUNPOD_API_KEY' +``` + +```python Python +import requests + +url = "https://api.runpod.io/v2/openapi.json" +headers = {"Authorization": "Bearer RUNPOD_API_KEY"} +response = requests.get(url, headers=headers) +print(response.json()) +``` + + From b9cd28d376171910aab60b25cb5204b3398db3d8 Mon Sep 17 00:00:00 2001 From: lgunreddi Date: Wed, 22 Jul 2026 10:52:40 -0400 Subject: [PATCH 36/41] Update overview.mdx --- api-reference-v2/overview.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/api-reference-v2/overview.mdx b/api-reference-v2/overview.mdx index 0db77954..339e0d19 100644 --- a/api-reference-v2/overview.mdx +++ b/api-reference-v2/overview.mdx @@ -5,17 +5,17 @@ description: "Programmatically manage Runpod resources using the API v2." --- - API v2 is currently in beta. Endpoints and behavior may change before general availability. + The REST API v2 is currently in beta. Endpoints and behavior may change before general availability. -The Runpod API v2 provides programmatic access to your Runpod resources over standard HTTP. Use it to create and manage Pods, query Serverless endpoints, provision storage, and retrieve billing data — without using the console. +The Runpod REST API v2 provides programmatic access to your Runpod resources over standard HTTP. Use it to create and manage Pods, query Serverless endpoints, provision storage, and retrieve billing data — without using the console. ## Base URL ``` https://api.runpod.io/v2 ``` -The Runpod API v2 provides programmatic access to all Runpod compute resources. Integrate GPU infrastructure into your applications, workflows, and automation systems. +The Runpod REST API v2 provides programmatic access to all Runpod compute resources. Integrate GPU infrastructure into your applications, workflows, and automation systems. ## Available resources From a8deed138865139b09c0a90e562298e222d4d294 Mon Sep 17 00:00:00 2001 From: lgunreddi Date: Wed, 22 Jul 2026 11:00:17 -0400 Subject: [PATCH 37/41] Update release-notes.mdx --- release-notes.mdx | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/release-notes.mdx b/release-notes.mdx index ebb7c240..5248f5cc 100644 --- a/release-notes.mdx +++ b/release-notes.mdx @@ -13,6 +13,10 @@ rss: true +**July 23, 2026** + +

New Release [Runpod API v2 (BETA)](/api-reference-v2/overview)

A new REST API is available in public beta. See the [API v2 reference](/api-reference-v2/overview) to get started. The [GraphQL API](/api-reference/overview) and REST API v1 continue to work for now, but will be deprecated in a future release, so new integrations should build on API v2. + **July 17, 2026**

New Release [Scale Instant Clusters - BETA](/instant-clusters/scale-clusters)

You can now add pods to a running Instant Cluster to increase GPU capacity without recreating it. New pods join the cluster's private network automatically, matching the existing GPU type, template, and network storage. Currently in beta for eligible accounts. From 207d01916e5ec3e206bab19add578ffab9f4a115 Mon Sep 17 00:00:00 2001 From: lgunreddi Date: Wed, 22 Jul 2026 14:31:14 -0400 Subject: [PATCH 38/41] Update docs.json --- docs.json | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/docs.json b/docs.json index 3c80213f..95487587 100644 --- a/docs.json +++ b/docs.json @@ -528,7 +528,16 @@ "pages": [ "api-reference-v2/overview" ] - }, + }, + { + "group": "Resources", + "pages": [ + "openapi": { + "source": "api-reference-v2/openapi.json", + "directory": "api-reference-v2" + } + ] + }, { "group": "Pods", "pages": [ From 06c3d8d96e6aad86378a7e29a635c4e82e216aa5 Mon Sep 17 00:00:00 2001 From: lgunreddi Date: Wed, 22 Jul 2026 15:31:35 -0400 Subject: [PATCH 39/41] Update docs.json --- docs.json | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs.json b/docs.json index 95487587..98d5c6f7 100644 --- a/docs.json +++ b/docs.json @@ -531,12 +531,10 @@ }, { "group": "Resources", - "pages": [ "openapi": { "source": "api-reference-v2/openapi.json", "directory": "api-reference-v2" - } - ] + } }, { "group": "Pods", From 3c690726a20e691cc6153bc7c571390251d804b6 Mon Sep 17 00:00:00 2001 From: lgunreddi Date: Wed, 22 Jul 2026 16:09:32 -0400 Subject: [PATCH 40/41] Update docs.json --- docs.json | 12 ++---------- 1 file changed, 2 insertions(+), 10 deletions(-) diff --git a/docs.json b/docs.json index 98d5c6f7..7a31cec3 100644 --- a/docs.json +++ b/docs.json @@ -528,14 +528,7 @@ "pages": [ "api-reference-v2/overview" ] - }, - { - "group": "Resources", - "openapi": { - "source": "api-reference-v2/openapi.json", - "directory": "api-reference-v2" - } - }, + }, { "group": "Pods", "pages": [ @@ -543,8 +536,7 @@ "api-reference-v2/pods/create-a-pod", "api-reference-v2/pods/get-a-pod", "api-reference-v2/pods/terminate-a-pod", - "api-reference-v2/pods/update-a-pod", - "api-reference-v2/pods/stream-pod-logs", + "api-reference-v2/pods/update-a-pod", "api-reference-v2/pods/trigger-a-pod-state-transition" ] }, From 93a471b81e42a5bd83304998aecff5d1015c3689 Mon Sep 17 00:00:00 2001 From: lgunreddi Date: Wed, 22 Jul 2026 17:24:48 -0400 Subject: [PATCH 41/41] Update docs.json --- docs.json | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs.json b/docs.json index 7a31cec3..da60be34 100644 --- a/docs.json +++ b/docs.json @@ -536,7 +536,8 @@ "api-reference-v2/pods/create-a-pod", "api-reference-v2/pods/get-a-pod", "api-reference-v2/pods/terminate-a-pod", - "api-reference-v2/pods/update-a-pod", + "api-reference-v2/pods/update-a-pod", + "api-reference-v2/pods/stream-pod-logs", "api-reference-v2/pods/trigger-a-pod-state-transition" ] },