{
  "openapi": "3.1.0",
  "info": {
    "title": "CloudGPU API",
    "version": "1.7.0",
    "summary": "OpenAI-compatible model API and per-minute GPU rental, on one API key and one prepaid USD balance.",
    "description": "CloudGPU (cloudgpu.app) offers two things behind one API key:\n\n1. **Model API**: an OpenAI-compatible endpoint (`/v1/chat/completions`, `/v1/images/generations`, `/v1/audio/*`) and the Claude Messages format (`/v1/messages`). Use any OpenAI SDK with `base_url = https://cloudgpu.app/v1`. `GET /v1/models` lists the models and needs no key.\n2. **GPU instances**: rent a GPU under source-specific minute or started-hour billing (`/v1/gpu/*`), with optional auto-shutdown limits (`max_minutes`, `max_spend_usd`, `idle_minutes`) that CloudGPU's servers enforce even after your client disconnects.\n3. **Agent compute discovery (no key needed)**: `GET /v1/public/gpu-catalog` lists GPU models, VRAM, live prices, billing rules and disk options; `POST /v1/quotes` estimates the cost of a task from VRAM, GPU count, template, disk size, duration and budget. Neither creates paid resources.\n\nAuthentication: `Authorization: Bearer <api key>` (keys start with `cgw-sk-`, created at https://cloudgpu.app/api). `x-api-key` is also accepted for Claude clients.\nBilling: prepaid USD balance; top up at https://cloudgpu.app/billing. When the balance runs out, running GPU instances are destroyed and their disks erased.\nErrors always look like `{\"error\": {\"type\", \"code\", \"message\"}}`.\nFor AI coding assistants there is an MCP server: `npx -y cloudgpu-mcp` (https://cloudgpu.app/docs/mcp).\n\nPersistent storage and Workspace endpoints are optional and return 503 until explicitly enabled. Check GET /v1/public/compute-capabilities. Full-disk restore and automatic output collection are not supported by this version.",
    "contact": {
      "name": "CloudGPU support",
      "email": "support@cloudgpu.app",
      "url": "https://cloudgpu.app/contact"
    },
    "termsOfService": "https://cloudgpu.app/terms"
  },
  "externalDocs": {
    "description": "API documentation",
    "url": "https://cloudgpu.app/api/docs"
  },
  "servers": [
    {
      "url": "https://cloudgpu.app",
      "description": "Production"
    }
  ],
  "security": [
    {
      "bearer": []
    }
  ],
  "tags": [
    {
      "name": "Models",
      "description": "OpenAI-compatible and Claude-compatible model API"
    },
    {
      "name": "GPU",
      "description": "Rent GPUs under source-specific minute or started-hour quotes"
    },
    {
      "name": "Agent Compute",
      "description": "Discover GPUs and get task quotes without an API key. Read-only; nothing here creates paid resources."
    }
  ],
  "paths": {
    "/v1/models": {
      "get": {
        "tags": [
          "Models"
        ],
        "operationId": "listModels",
        "summary": "List models",
        "description": "Every model you can call, with per-token prices in USD per 1M tokens where they apply. No API key needed.",
        "security": [],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "object": {
                      "const": "list"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Model"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/chat/completions": {
      "post": {
        "tags": [
          "Models"
        ],
        "operationId": "createChatCompletion",
        "summary": "Create a chat completion",
        "description": "OpenAI Chat Completions format, including streaming (`stream: true`), tools / function calling and JSON mode where the model supports them. Billed per token at the rates in GET /v1/models.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "model",
                  "messages"
                ],
                "properties": {
                  "model": {
                    "type": "string",
                    "description": "A model id from GET /v1/models"
                  },
                  "messages": {
                    "type": "array",
                    "description": "Conversation so far, OpenAI message format",
                    "items": {
                      "type": "object",
                      "properties": {
                        "role": {
                          "enum": [
                            "system",
                            "user",
                            "assistant",
                            "tool"
                          ]
                        },
                        "content": {}
                      }
                    }
                  },
                  "stream": {
                    "type": "boolean",
                    "description": "Stream the response as server-sent events"
                  },
                  "max_tokens": {
                    "type": "integer",
                    "description": "Upper bound on generated tokens"
                  },
                  "temperature": {
                    "type": "number"
                  },
                  "tools": {
                    "type": "array",
                    "description": "Function definitions the model may call",
                    "items": {
                      "type": "object"
                    }
                  }
                }
              },
              "example": {
                "model": "deepseek-v4-flash",
                "messages": [
                  {
                    "role": "user",
                    "content": "Say hi"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "OpenAI chat.completion object (or an SSE stream of chat.completion.chunk when stream is true)"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "402": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/v1/messages": {
      "post": {
        "tags": [
          "Models"
        ],
        "operationId": "createMessage",
        "summary": "Create a message (Claude format)",
        "description": "Claude Messages API format, for Claude Code and the anthropic SDKs. Point ANTHROPIC_BASE_URL at https://cloudgpu.app and use your CloudGPU key.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "model",
                  "messages",
                  "max_tokens"
                ],
                "properties": {
                  "model": {
                    "type": "string"
                  },
                  "messages": {
                    "type": "array",
                    "items": {
                      "type": "object"
                    }
                  },
                  "max_tokens": {
                    "type": "integer"
                  },
                  "stream": {
                    "type": "boolean"
                  },
                  "system": {}
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "402": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/v1/messages/count_tokens": {
      "post": {
        "tags": [
          "Models"
        ],
        "operationId": "countTokens",
        "summary": "Count tokens (Claude format)",
        "description": "Token count for a Messages request, without running it.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "input_tokens": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/v1/images/generations": {
      "post": {
        "tags": [
          "Models"
        ],
        "operationId": "createImage",
        "summary": "Generate an image",
        "description": "OpenAI Images format. Image size is capped at about 1 megapixel. Billed per image.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "model",
                  "prompt"
                ],
                "properties": {
                  "model": {
                    "type": "string",
                    "description": "An image model id from GET /v1/models"
                  },
                  "prompt": {
                    "type": "string"
                  },
                  "size": {
                    "type": "string",
                    "example": "1024x1024"
                  },
                  "n": {
                    "type": "integer"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "402": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/v1/audio/speech": {
      "post": {
        "tags": [
          "Models"
        ],
        "operationId": "createSpeech",
        "summary": "Text to speech",
        "description": "OpenAI audio/speech format; returns audio bytes. Billed per character.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "model",
                  "input"
                ],
                "properties": {
                  "model": {
                    "type": "string"
                  },
                  "input": {
                    "type": "string"
                  },
                  "voice": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Audio",
            "content": {
              "audio/mpeg": {}
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "402": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/v1/audio/transcriptions": {
      "post": {
        "tags": [
          "Models"
        ],
        "operationId": "createTranscription",
        "summary": "Speech to text",
        "description": "OpenAI audio/transcriptions format (multipart upload). Billed per second of audio.",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "model",
                  "file"
                ],
                "properties": {
                  "model": {
                    "type": "string"
                  },
                  "file": {
                    "type": "string",
                    "format": "binary"
                  },
                  "language": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "text": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "402": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/v1/gpu/account": {
      "get": {
        "tags": [
          "GPU"
        ],
        "operationId": "getGpuAccount",
        "summary": "Account balance and limits",
        "description": "Balance in USD, how many instances this account may run at once (depends on its top-up history), and how many are running now. Check it before renting.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Account"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/v1/gpu/offers": {
      "get": {
        "tags": [
          "GPU"
        ],
        "operationId": "listGpuOffers",
        "summary": "GPUs for rent",
        "description": "Every GPU model on sale with VRAM, the live price per GPU-hour (billing period and minimum charge depend on the quoted source) and availability. Prices and availability change during the day; read them right before renting.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "object",
                    "data"
                  ],
                  "properties": {
                    "object": {
                      "const": "list"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Offer"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/v1/gpu/templates": {
      "get": {
        "tags": [
          "GPU"
        ],
        "operationId": "listGpuTemplates",
        "summary": "Instance templates",
        "description": "Ready-made images (JupyterLab, Ollama, ComfyUI / FLUX, LLaMA-Factory and others) with the GPU each recommends. Templates with has_api_endpoint get a public HTTPS api_url.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "object",
                    "data"
                  ],
                  "properties": {
                    "object": {
                      "const": "list"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Template"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/v1/gpu/instances": {
      "get": {
        "tags": [
          "GPU"
        ],
        "operationId": "listGpuInstances",
        "summary": "List instances",
        "description": "Running and starting instances, plus those stopped in the last 7 days.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "object",
                    "data"
                  ],
                  "properties": {
                    "object": {
                      "const": "list"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Instance"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error"
          }
        }
      },
      "post": {
        "tags": [
          "GPU"
        ],
        "operationId": "createGpuInstance",
        "summary": "Rent a GPU",
        "description": "Starts an instance and returns at once with status `creating`. Poll GET /v1/gpu/instances/{id} until it is `running`. Nothing is charged if it ends up `failed`. Give gpu_model, template, or both.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "gpu_model": {
                    "type": "string",
                    "description": "GPU model exactly as GET /v1/gpu/offers lists it. Use \"auto\" (or omit it together with a template) to let us pick an available GPU that can run the request, choosing by price; if the GPU you name cannot run the template, the error lists GPUs that can, with current prices."
                  },
                  "template": {
                    "type": "string",
                    "description": "Template id from GET /v1/gpu/templates; omit for a plain GPU with Python and CUDA"
                  },
                  "gpu_count": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 8,
                    "description": "Number of GPUs (at least the offer's min_gpu_count)"
                  },
                  "max_minutes": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 10080,
                    "description": "Destroy the instance this many minutes after it starts (enforced server-side)"
                  },
                  "max_spend_usd": {
                    "type": "number",
                    "exclusiveMinimum": 0,
                    "description": "Destroy the instance before it would cost more than this (enforced server-side)"
                  },
                  "idle_minutes": {
                    "type": "integer",
                    "description": "Destroy after the GPU has been idle this long; 10–1440, 0 = off (enforced server-side). Package installs and downloads count as idle."
                  },
                  "setup_script": {
                    "type": "string",
                    "maxLength": 16384,
                    "description": "Optional bash script run once as root in the background after the instance is handed over. Saved at /root/cloudgpu-setup.sh; output in /root/cloudgpu-setup.log. Up to 16 KB."
                  },
                  "quote_id": {
                    "type": "string",
                    "description": "Optional id from POST /v1/quotes. gpu_count, template and disk_gb left out are taken from the quote; ones you send must match it. Fails with 409 and starts nothing: quote_expired (request a new quote), gpu_unavailable (choose another GPU), price_changed (re-quote and check the budget), quote_mismatch (fix the configuration). Insufficient balance returns 402 insufficient_balance."
                  }
                }
              },
              "example": {
                "gpu_model": "RTX 4090",
                "max_minutes": 120,
                "max_spend_usd": 2,
                "idle_minutes": 30
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Accepted; status is creating",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Instance"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "402": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/v1/gpu/instances/{id}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "Instance id returned by POST /v1/gpu/instances",
          "schema": {
            "type": "string"
          }
        }
      ],
      "get": {
        "tags": [
          "GPU"
        ],
        "operationId": "getGpuInstance",
        "summary": "Get an instance",
        "description": "Status, cost so far, SSH login once running, the public api_url for API templates, and the auto-shutdown limits.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Instance"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/Error"
          }
        }
      },
      "delete": {
        "tags": [
          "GPU"
        ],
        "operationId": "destroyGpuInstance",
        "summary": "Destroy an instance",
        "description": "Stops billing and erases the instance's disk. Download results first. Billing is per minute, and unused prepaid time is refunded to the balance.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Instance"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/v1/gpu/instances/{id}/destroy": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "Instance id returned by POST /v1/gpu/instances",
          "schema": {
            "type": "string"
          }
        }
      ],
      "post": {
        "tags": [
          "GPU"
        ],
        "operationId": "destroyGpuInstancePost",
        "summary": "Destroy an instance (POST)",
        "description": "Same as DELETE /v1/gpu/instances/{id}, for clients that cannot send DELETE.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Instance"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/v1/public/gpu-catalog": {
      "get": {
        "tags": [
          "Agent Compute"
        ],
        "operationId": "getGpuCatalog",
        "security": [],
        "summary": "Public GPU catalog (no key)",
        "description": "Discover GPU compute offerings on CloudGPU: GPU model, VRAM, live price per GPU-hour, availability (available / limited / unavailable), billing rules (per minute, 1-minute minimum, one hour pre-authorised), system disk options with their hourly add-on, ready templates and features. Read-only: this does not create paid resources. Cache for `cache_ttl_seconds`.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "object": {
                      "const": "gpu.catalog"
                    },
                    "schema_version": {
                      "type": "string"
                    },
                    "currency": {
                      "const": "USD"
                    },
                    "pricing_unit": {
                      "const": "gpu_hour"
                    },
                    "generated_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "cache_ttl_seconds": {
                      "type": "integer"
                    },
                    "billing": {
                      "type": "object"
                    },
                    "disk_options": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "features": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "templates": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "gpus": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "model": {
                            "type": "string"
                          },
                          "vram_gb": {
                            "type": [
                              "integer",
                              "null"
                            ]
                          },
                          "price_per_gpu_hour_usd": {
                            "type": "number"
                          },
                          "min_gpu_count": {
                            "type": "integer"
                          },
                          "availability": {
                            "enum": [
                              "available",
                              "limited",
                              "unavailable"
                            ]
                          },
                          "tier": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limited"
          }
        }
      }
    },
    "/v1/quotes": {
      "post": {
        "tags": [
          "Agent Compute"
        ],
        "operationId": "createQuote",
        "security": [],
        "summary": "Quote a GPU task (no key)",
        "description": "Estimate what a task would cost. Filters GPUs by VRAM, GPU count, template and system disk, then returns candidates sorted by estimated total cost, each with its hourly price, billed minutes, estimated total and the balance needed to start. The quote expires after 5 minutes and is an estimate: price, stock and balance are checked again when you start an instance, and a changed price returns an error rather than a dearer GPU. This does not create paid resources. Send an API key to also learn whether your balance can start each candidate (can_start_with_balance).",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "requirements": {
                    "type": "object",
                    "properties": {
                      "min_vram_gb": {
                        "type": "integer"
                      },
                      "gpu_count": {
                        "type": "integer",
                        "default": 1
                      },
                      "gpu_model": {
                        "type": "string"
                      },
                      "template": {
                        "type": "string"
                      },
                      "disk_gb": {
                        "enum": [
                          0,
                          100,
                          200,
                          500
                        ]
                      }
                    }
                  },
                  "estimated_duration_seconds": {
                    "type": "integer",
                    "default": 3600
                  },
                  "max_budget_usd": {
                    "type": "string"
                  },
                  "sort_by": {
                    "enum": [
                      "estimated_total_cost",
                      "vram"
                    ]
                  }
                }
              },
              "example": {
                "requirements": {
                  "min_vram_gb": 24,
                  "gpu_count": 1
                },
                "estimated_duration_seconds": 1800,
                "max_budget_usd": "1.00"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Quote"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "description": "Rate limited"
          }
        }
      }
    },
    "/v1/quotes/{id}": {
      "get": {
        "tags": [
          "Agent Compute"
        ],
        "operationId": "getQuote",
        "security": [],
        "summary": "Read a quote (no key)",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Quote"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/v1/jobs": {
      "post": {
        "tags": [
          "Jobs"
        ],
        "operationId": "createJob",
        "summary": "Run one command on a GPU, start to finish",
        "description": "CloudGPU starts a GPU, runs the command, then destroys the GPU, on its servers. Safe to retry with the same Idempotency-Key.",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "maxLength": 128
            },
            "description": "Required. A unique value per job, for example a UUID. Resending the same request with the same key returns the same job (HTTP 200, header Idempotent-Replayed: true) and never starts a second GPU. The same key with different parameters returns 409 idempotency_key_reused."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/JobRequest"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Accepted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                }
              }
            }
          },
          "200": {
            "description": "Same Idempotency-Key and same request: the existing job",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "402": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        }
      },
      "get": {
        "tags": [
          "Jobs"
        ],
        "operationId": "listJobs",
        "summary": "Recent jobs",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20,
              "maximum": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "object": {
                      "type": "string"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Job"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/v1/jobs/{id}": {
      "get": {
        "tags": [
          "Jobs"
        ],
        "operationId": "getJob",
        "summary": "Job status, exit code and cost",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/v1/jobs/{id}/events": {
      "get": {
        "tags": [
          "Jobs"
        ],
        "operationId": "getJobEvents",
        "summary": "The job's history",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "event": {
                            "type": "string"
                          },
                          "from_status": {
                            "type": "string",
                            "nullable": true
                          },
                          "to_status": {
                            "type": "string",
                            "nullable": true
                          },
                          "detail": {
                            "type": "string"
                          },
                          "at": {
                            "type": "integer"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/v1/jobs/{id}/logs": {
      "get": {
        "tags": [
          "Jobs"
        ],
        "operationId": "getJobLogs",
        "summary": "The last ~4 KB of the command's output",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "job_id": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string"
                    },
                    "tail": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/v1/jobs/{id}/cancel": {
      "post": {
        "tags": [
          "Jobs"
        ],
        "operationId": "cancelJob",
        "summary": "Cancel a job; its GPU is destroyed",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/v1/agent/connect": {
      "post": {
        "tags": [
          "Agent connect"
        ],
        "operationId": "startAgentConnect",
        "security": [],
        "summary": "Ask the account owner for a key with a budget (no key)",
        "description": "Returns a link for the account owner to open, sign in and approve. Then poll POST /v1/agent/connect/token.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "agent_name",
                  "spend_limit_usd"
                ],
                "properties": {
                  "agent_name": {
                    "type": "string",
                    "maxLength": 64
                  },
                  "spend_limit_usd": {
                    "type": "number",
                    "minimum": 1,
                    "maximum": 10000
                  },
                  "max_concurrent": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 10,
                    "default": 1
                  },
                  "expires_in_days": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 90,
                    "default": 30
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "device_code": {
                      "type": "string",
                      "description": "Secret; keep it in the agent"
                    },
                    "user_code": {
                      "type": "string",
                      "example": "ABCD-EFGH"
                    },
                    "verification_uri": {
                      "type": "string"
                    },
                    "verification_uri_complete": {
                      "type": "string"
                    },
                    "expires_in": {
                      "type": "integer"
                    },
                    "interval": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/v1/agent/connect/token": {
      "post": {
        "tags": [
          "Agent connect"
        ],
        "operationId": "finishAgentConnect",
        "security": [],
        "summary": "Collect the key once the owner approved (no key)",
        "description": "400 authorization_pending until approved; 403 access_denied if declined; 400 expired_token after 10 minutes or once the key was delivered. The key is returned once.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "device_code"
                ],
                "properties": {
                  "device_code": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Approved",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "api_key": {
                      "type": "string"
                    },
                    "key_id": {
                      "type": "string"
                    },
                    "agent_name": {
                      "type": "string"
                    },
                    "spend_limit_usd": {
                      "type": "string"
                    },
                    "max_concurrent": {
                      "type": "integer"
                    },
                    "expires_at": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/v1/public/compute-capabilities": {
      "get": {
        "tags": [
          "Agent persistence"
        ],
        "summary": "Discover enabled compute features",
        "description": "Public feature discovery, no API key required. Read actual account storage eligibility, quotas, retention and charges through GET /v1/storage before using persistence.",
        "security": [],
        "responses": {
          "200": {
            "description": "Live feature flags; no purchase or execution authorization",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "jobs": {
                      "type": "boolean"
                    },
                    "storage": {
                      "type": "boolean"
                    },
                    "workspaces": {
                      "type": "boolean"
                    },
                    "artifacts": {
                      "type": "boolean"
                    },
                    "apply_workspace": {
                      "type": "boolean"
                    },
                    "model_references": {
                      "type": "boolean"
                    },
                    "prepare_model_deployment": {
                      "type": "boolean"
                    },
                    "job_rerun": {
                      "type": "boolean"
                    },
                    "model_registry": {
                      "type": "boolean"
                    },
                    "full_disk_restore": {
                      "type": "boolean"
                    },
                    "automatic_output_collection": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/v1/storage": {
      "get": {
        "tags": [
          "Agent persistence"
        ],
        "summary": "Storage usage, reservations, quota and retention policy",
        "description": "Requires enabled storage and a funded account. Read GET /v1/storage for actual quota, retention and pricing; downloads do not extend expires_at. Signed URLs are short-lived credentials; do not log them.",
        "security": [
          {
            "bearer": []
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation"
          },
          "400": {
            "description": "Invalid request, quota exceeded or resource not owned by caller"
          },
          "401": {
            "description": "Missing, revoked or expired API key"
          },
          "503": {
            "description": "Persistent storage is not enabled or unavailable"
          }
        }
      }
    },
    "/v1/files": {
      "get": {
        "tags": [
          "Agent persistence"
        ],
        "summary": "List persistent files",
        "description": "Requires enabled storage and a funded account. Read GET /v1/storage for actual quota, retention and pricing; downloads do not extend expires_at. Signed URLs are short-lived credentials; do not log them.",
        "security": [
          {
            "bearer": []
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation"
          },
          "400": {
            "description": "Invalid request, quota exceeded or resource not owned by caller"
          },
          "401": {
            "description": "Missing, revoked or expired API key"
          },
          "503": {
            "description": "Persistent storage is not enabled or unavailable"
          }
        }
      },
      "post": {
        "tags": [
          "Agent persistence"
        ],
        "summary": "Reserve quota and start a multipart file upload",
        "description": "Requires enabled storage and a funded account. Read GET /v1/storage for actual quota, retention and pricing; downloads do not extend expires_at. Signed URLs are short-lived credentials; do not log them.",
        "security": [
          {
            "bearer": []
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation"
          },
          "400": {
            "description": "Invalid request, quota exceeded or resource not owned by caller"
          },
          "401": {
            "description": "Missing, revoked or expired API key"
          },
          "503": {
            "description": "Persistent storage is not enabled or unavailable"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "purpose": {
                    "type": "string",
                    "enum": [
                      "artifact",
                      "workspace",
                      "model",
                      "dataset"
                    ]
                  },
                  "size_bytes": {
                    "type": "integer",
                    "format": "int64",
                    "minimum": 0
                  },
                  "accept_storage_charges": {
                    "type": "boolean",
                    "default": false,
                    "description": "Required to exceed the included allowance. Read GET /v1/storage pricing and obtain user agreement first; storage charges are separate from GPU Job budgets."
                  }
                },
                "required": [
                  "name",
                  "purpose",
                  "size_bytes"
                ]
              }
            }
          }
        }
      }
    },
    "/v1/files/{id}/parts/{part}": {
      "post": {
        "tags": [
          "Agent persistence"
        ],
        "summary": "Get a 15-minute URL for one exact-size upload part",
        "description": "Requires enabled storage and a funded account. Read GET /v1/storage for actual quota, retention and pricing; downloads do not extend expires_at. Signed URLs are short-lived credentials; do not log them.",
        "security": [
          {
            "bearer": []
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation"
          },
          "400": {
            "description": "Invalid request, quota exceeded or resource not owned by caller"
          },
          "401": {
            "description": "Missing, revoked or expired API key"
          },
          "503": {
            "description": "Persistent storage is not enabled or unavailable"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "part",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        ]
      }
    },
    "/v1/files/{id}/complete": {
      "post": {
        "tags": [
          "Agent persistence"
        ],
        "summary": "Verify every part and commit an immutable file",
        "description": "Requires enabled storage and a funded account. Read GET /v1/storage for actual quota, retention and pricing; downloads do not extend expires_at. Signed URLs are short-lived credentials; do not log them.",
        "security": [
          {
            "bearer": []
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation"
          },
          "400": {
            "description": "Invalid request, quota exceeded or resource not owned by caller"
          },
          "401": {
            "description": "Missing, revoked or expired API key"
          },
          "503": {
            "description": "Persistent storage is not enabled or unavailable"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/v1/files/{id}/download": {
      "post": {
        "tags": [
          "Agent persistence"
        ],
        "summary": "Authorize one file download; authorization does not prove transfer completion",
        "description": "Requires enabled storage and a funded account. Read GET /v1/storage for actual quota, retention and pricing; downloads do not extend expires_at. Signed URLs are short-lived credentials; do not log them.",
        "security": [
          {
            "bearer": []
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation"
          },
          "400": {
            "description": "Invalid request, quota exceeded or resource not owned by caller"
          },
          "401": {
            "description": "Missing, revoked or expired API key"
          },
          "503": {
            "description": "Persistent storage is not enabled or unavailable"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "destination",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "user",
                "gpu"
              ],
              "default": "user"
            }
          }
        ]
      }
    },
    "/v1/files/{id}": {
      "delete": {
        "tags": [
          "Agent persistence"
        ],
        "summary": "Delete an unpinned file, or cancel an unfinished upload",
        "description": "Requires enabled storage and a funded account. Read GET /v1/storage for actual quota, retention and pricing; downloads do not extend expires_at. Signed URLs are short-lived credentials; do not log them.",
        "security": [
          {
            "bearer": []
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation"
          },
          "400": {
            "description": "Invalid request, quota exceeded or resource not owned by caller"
          },
          "401": {
            "description": "Missing, revoked or expired API key"
          },
          "503": {
            "description": "Persistent storage is not enabled or unavailable"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/v1/workspaces": {
      "get": {
        "tags": [
          "Agent persistence"
        ],
        "summary": "List saved project Workspaces",
        "description": "Requires enabled storage and a funded account. Read GET /v1/storage for actual quota, retention and pricing; downloads do not extend expires_at. Signed URLs are short-lived credentials; do not log them.",
        "security": [
          {
            "bearer": []
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation"
          },
          "400": {
            "description": "Invalid request, quota exceeded or resource not owned by caller"
          },
          "401": {
            "description": "Missing, revoked or expired API key"
          },
          "503": {
            "description": "Persistent storage is not enabled or unavailable"
          }
        }
      },
      "post": {
        "tags": [
          "Agent persistence"
        ],
        "summary": "Create a named project Workspace",
        "description": "Requires enabled storage and a funded account. Read GET /v1/storage for actual quota, retention and pricing; downloads do not extend expires_at. Signed URLs are short-lived credentials; do not log them.",
        "security": [
          {
            "bearer": []
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation"
          },
          "400": {
            "description": "Invalid request, quota exceeded or resource not owned by caller"
          },
          "401": {
            "description": "Missing, revoked or expired API key"
          },
          "503": {
            "description": "Persistent storage is not enabled or unavailable"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  }
                },
                "required": [
                  "name"
                ]
              }
            }
          }
        }
      }
    },
    "/v1/workspaces/{id}/versions": {
      "get": {
        "tags": [
          "Agent persistence"
        ],
        "summary": "List immutable Workspace versions",
        "description": "Requires enabled storage and a funded account. Read GET /v1/storage for actual quota, retention and pricing; downloads do not extend expires_at. Signed URLs are short-lived credentials; do not log them.",
        "security": [
          {
            "bearer": []
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation"
          },
          "400": {
            "description": "Invalid request, quota exceeded or resource not owned by caller"
          },
          "401": {
            "description": "Missing, revoked or expired API key"
          },
          "503": {
            "description": "Persistent storage is not enabled or unavailable"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      },
      "post": {
        "tags": [
          "Agent persistence"
        ],
        "summary": "Save a relative-project-path to owned ready file_id manifest",
        "description": "Requires enabled storage and a funded account. Read GET /v1/storage for actual quota, retention and pricing; downloads do not extend expires_at. Signed URLs are short-lived credentials; do not log them.",
        "security": [
          {
            "bearer": []
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation"
          },
          "400": {
            "description": "Invalid request, quota exceeded or resource not owned by caller"
          },
          "401": {
            "description": "Missing, revoked or expired API key"
          },
          "503": {
            "description": "Persistent storage is not enabled or unavailable"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": {
                  "type": "string",
                  "pattern": "^file_[0-9a-f]{32}$"
                },
                "minProperties": 1,
                "maxProperties": 1000
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/v1/workspace-versions/{id}": {
      "get": {
        "tags": [
          "Agent persistence"
        ],
        "summary": "Read a Workspace version",
        "description": "Requires enabled storage and a funded account. Read GET /v1/storage for actual quota, retention and pricing; downloads do not extend expires_at. Signed URLs are short-lived credentials; do not log them.",
        "security": [
          {
            "bearer": []
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation"
          },
          "400": {
            "description": "Invalid request, quota exceeded or resource not owned by caller"
          },
          "401": {
            "description": "Missing, revoked or expired API key"
          },
          "503": {
            "description": "Persistent storage is not enabled or unavailable"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      },
      "delete": {
        "tags": [
          "Agent persistence"
        ],
        "summary": "Delete a version not referenced by an active Job",
        "description": "Requires enabled storage and a funded account. Read GET /v1/storage for actual quota, retention and pricing; downloads do not extend expires_at. Signed URLs are short-lived credentials; do not log them.",
        "security": [
          {
            "bearer": []
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation"
          },
          "400": {
            "description": "Invalid request, quota exceeded or resource not owned by caller"
          },
          "401": {
            "description": "Missing, revoked or expired API key"
          },
          "503": {
            "description": "Persistent storage is not enabled or unavailable"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/v1/workspace-instances": {
      "get": {
        "tags": [
          "Agent persistence"
        ],
        "operationId": "listWorkspaceInstances",
        "summary": "List running GPUs available for Workspace application",
        "description": "Requires enabled apply_workspace capability and a funded account. Budgeted Agent keys can only access instances created by the same key. No SSH credentials or signed URLs are returned.",
        "responses": {
          "200": {
            "description": "Application status, or list of owned running instances"
          },
          "400": {
            "description": "Invalid or unowned resource, unavailable SSH or disabled application feature"
          },
          "401": {
            "description": "Missing or invalid authorization"
          },
          "403": {
            "description": "Funding required, suspended account or disallowed key"
          },
          "429": {
            "description": "Rate limit"
          },
          "503": {
            "description": "Storage unavailable"
          }
        }
      }
    },
    "/v1/workspace-versions/{id}/applications/{instance}": {
      "post": {
        "tags": [
          "Agent persistence"
        ],
        "operationId": "applyWorkspace",
        "summary": "Apply saved project files to an existing running GPU",
        "description": "Requires enabled apply_workspace capability and a funded account. Budgeted Agent keys can only access instances created by the same key. No SSH credentials or signed URLs are returned. Ask the user first. Restores into a new private directory; does not install dependencies, execute code, overwrite existing project files or create/restart/stop an instance. Rental billing continues. Repeating the same user/version/instance returns existing state; never automatically retry a failed or uncertain application. Do not delete the source version during restore.",
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "instance",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Application status, or list of owned running instances"
          },
          "400": {
            "description": "Invalid or unowned resource, unavailable SSH or disabled application feature"
          },
          "401": {
            "description": "Missing or invalid authorization"
          },
          "403": {
            "description": "Funding required, suspended account or disallowed key"
          },
          "429": {
            "description": "Rate limit"
          },
          "503": {
            "description": "Storage unavailable"
          }
        }
      },
      "get": {
        "tags": [
          "Agent persistence"
        ],
        "operationId": "getWorkspaceApplication",
        "summary": "Check Workspace application on a running GPU",
        "description": "Requires enabled apply_workspace capability and a funded account. Budgeted Agent keys can only access instances created by the same key. No SSH credentials or signed URLs are returned. States: not_started, applying, applied, failed, busy, conflict, needs_attention. Applied includes the project path. Status survives backend restarts on the target GPU, but is not available after the instance ends. It is not billing or release evidence.",
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "instance",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Application status, or list of owned running instances"
          },
          "400": {
            "description": "Invalid or unowned resource, unavailable SSH or disabled application feature"
          },
          "401": {
            "description": "Missing or invalid authorization"
          },
          "403": {
            "description": "Funding required, suspended account or disallowed key"
          },
          "429": {
            "description": "Rate limit"
          },
          "503": {
            "description": "Storage unavailable"
          }
        }
      }
    },
    "/v1/jobs/{id}/rerun-spec": {
      "get": {
        "tags": [
          "Jobs"
        ],
        "operationId": "prepareJobRerun",
        "summary": "Read successful Job parameters for a new approved task",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Read-only prepared parameters; this does not submit a Job",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JobRerunSpec"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/v1/jobs/prepare-model-deployment": {
      "post": {
        "tags": [
          "Jobs"
        ],
        "operationId": "prepareModelDeployment",
        "summary": "Prepare a model/workflow setup script without starting a GPU",
        "description": "Authenticated account eligibility applies. Model names must be ComfyUI categories such as checkpoints, loras or vae. Review the returned script and obtain budget approval before using the existing deployment flow. Does not guarantee model/image compatibility.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "model_references"
                ],
                "properties": {
                  "model_references": {
                    "type": "array",
                    "maxItems": 4,
                    "items": {
                      "$ref": "#/components/schemas/ModelReference"
                    },
                    "description": "Pinned public files, at most 100 GB across all references. Downloads go directly to the rented GPU after Workspace restore and consume the same time/spend limits. No platform model cache, dependency install or remote repository code execution.",
                    "minItems": 1
                  },
                  "workflow": {
                    "type": "object",
                    "description": "Optional ComfyUI UI-format workflow with at most 200 nodes. Nodes are not installed and the graph is not executed."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Prepared script; no GPU created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "template_id": {
                      "type": "string"
                    },
                    "setup_script": {
                      "type": "string"
                    },
                    "starts_gpu": {
                      "type": "boolean",
                      "const": false
                    },
                    "requires_review": {
                      "type": "boolean",
                      "const": true
                    },
                    "model_references": {
                      "type": "array",
                      "maxItems": 4,
                      "items": {
                        "$ref": "#/components/schemas/ModelReference"
                      },
                      "description": "Pinned public files, at most 100 GB across all references. Downloads go directly to the rented GPU after Workspace restore and consume the same time/spend limits. No platform model cache, dependency install or remote repository code execution."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          },
          "503": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/v1/public/agent-self-check": {
      "get": {
        "summary": "Anonymous read-only capabilities, billing, evidence and known limitations",
        "responses": {
          "200": {
            "description": "Success; consult returned runtime state"
          },
          "400": {
            "description": "Invalid request"
          },
          "503": {
            "description": "Unavailable or rollout disabled"
          }
        },
        "security": []
      }
    },
    "/v1/public/task-fit": {
      "post": {
        "summary": "Read-only task suitability; never submits work or guarantees a GPU",
        "responses": {
          "200": {
            "description": "Success; consult returned runtime state"
          },
          "400": {
            "description": "Invalid request"
          },
          "503": {
            "description": "Unavailable or rollout disabled"
          }
        },
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "task_type": {
                    "type": "string",
                    "enum": [
                      "gpu_environment_check",
                      "python_batch",
                      "comfyui_video",
                      "causal_lm_lora"
                    ]
                  },
                  "requires_kernel_control": {
                    "type": "boolean"
                  },
                  "needs_persistent_outputs": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/storage/budget/quotes": {
      "post": {
        "summary": "Quote earmarked storage budget transfer; owner approval required separately",
        "responses": {
          "200": {
            "description": "Success; consult returned runtime state"
          },
          "400": {
            "description": "Invalid request"
          },
          "503": {
            "description": "Unavailable or rollout disabled"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "action": {
                    "type": "string",
                    "enum": [
                      "reserve",
                      "release"
                    ]
                  },
                  "amount_usd": {
                    "type": "number",
                    "exclusiveMinimum": 0,
                    "maximum": 1000000
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/storage/budget/quotes/{id}/confirm": {
      "post": {
        "summary": "Confirm exact owned quote once; repeated confirmation cannot debit twice",
        "responses": {
          "200": {
            "description": "Success; consult returned runtime state"
          },
          "400": {
            "description": "Invalid request"
          },
          "503": {
            "description": "Unavailable or rollout disabled"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "user_confirmed": {
                    "type": "boolean",
                    "enum": [
                      true
                    ]
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/files/{id}/upload": {
      "get": {
        "summary": "List owned unexpired multipart upload and completed parts for resumption",
        "responses": {
          "200": {
            "description": "Success; consult returned runtime state"
          },
          "400": {
            "description": "Invalid request"
          },
          "503": {
            "description": "Unavailable or rollout disabled"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/v1/billing/top-up-link": {
      "post": {
        "summary": "Create human payment link only; no checkout or payment authority",
        "responses": {
          "200": {
            "description": "Success; consult returned runtime state"
          },
          "400": {
            "description": "Invalid request"
          },
          "503": {
            "description": "Unavailable or rollout disabled"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "amount_usd": {
                    "type": "number",
                    "minimum": 1,
                    "maximum": 10000
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "CloudGPU API key (cgw-sk-...), from https://cloudgpu.app/api"
      }
    },
    "responses": {
      "Error": {
        "description": "Error",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "example": "invalid_request_error"
              },
              "code": {
                "type": "string",
                "example": "insufficient_balance"
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      },
      "Model": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Use this as `model` in requests"
          },
          "object": {
            "const": "model"
          },
          "owned_by": {
            "type": "string"
          },
          "input_usd_per_1m": {
            "type": [
              "number",
              "null"
            ],
            "description": "USD per 1M input tokens"
          },
          "output_usd_per_1m": {
            "type": [
              "number",
              "null"
            ],
            "description": "USD per 1M output tokens"
          },
          "cached_input_usd_per_1m": {
            "type": [
              "number",
              "null"
            ],
            "description": "USD per 1M cached input tokens"
          },
          "description": {
            "type": "string"
          }
        }
      },
      "Account": {
        "type": "object",
        "properties": {
          "object": {
            "const": "account"
          },
          "balance_usd": {
            "type": "number"
          },
          "gpu_api_enabled": {
            "type": "boolean"
          },
          "max_running_instances": {
            "type": "integer",
            "description": "Instances this account may run or start at once"
          },
          "running_instances": {
            "type": [
              "integer",
              "null"
            ]
          },
          "billing": {
            "type": "string"
          },
          "top_up_url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "Offer": {
        "type": "object",
        "properties": {
          "gpu_model": {
            "type": "string",
            "example": "RTX 4090"
          },
          "object": {
            "const": "gpu.offer"
          },
          "vram_gb": {
            "type": "integer"
          },
          "hourly_usd": {
            "type": "number",
            "description": "Price per GPU per hour; inspect the source-specific quote for billing period and minimum charge"
          },
          "available": {
            "enum": [
              "none",
              "low",
              "ok"
            ],
            "description": "Live availability bucket"
          },
          "min_gpu_count": {
            "type": "integer"
          },
          "tier": {
            "type": "string"
          }
        }
      },
      "Template": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "ollama"
          },
          "object": {
            "const": "gpu.template"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "recommended_gpu": {
            "type": "string"
          },
          "min_gpu_count": {
            "type": "integer"
          },
          "estimated_vram_gb": {
            "type": [
              "integer",
              "null"
            ]
          },
          "has_api_endpoint": {
            "type": "boolean",
            "description": "Instance gets a public HTTPS api_url"
          }
        }
      },
      "Limits": {
        "type": [
          "object",
          "null"
        ],
        "description": "Auto-shutdown settings given at creation",
        "properties": {
          "max_minutes": {
            "type": [
              "integer",
              "null"
            ]
          },
          "max_spend_usd": {
            "type": [
              "number",
              "null"
            ]
          },
          "idle_minutes": {
            "type": [
              "integer",
              "null"
            ]
          },
          "expires_at": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Unix time when max_minutes ends the instance"
          },
          "stopped_by": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "max_minutes",
              "max_spend",
              "idle",
              null
            ],
            "description": "Which limit ended the instance, if one did"
          }
        }
      },
      "Instance": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "object": {
            "const": "gpu.instance"
          },
          "gpu_model": {
            "type": "string"
          },
          "gpu_count": {
            "type": "integer"
          },
          "template": {
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "enum": [
              "creating",
              "running",
              "stopped",
              "failed"
            ]
          },
          "hourly_usd": {
            "type": "number",
            "description": "Price per hour for the whole instance"
          },
          "created_at": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Unix seconds"
          },
          "started_at": {
            "type": [
              "integer",
              "null"
            ]
          },
          "stopped_at": {
            "type": [
              "integer",
              "null"
            ]
          },
          "running_minutes": {
            "type": [
              "integer",
              "null"
            ]
          },
          "cost_usd": {
            "type": [
              "number",
              "null"
            ],
            "description": "Spent so far while running; final charge once stopped"
          },
          "ssh": {
            "type": [
              "object",
              "null"
            ],
            "description": "SSH login once running",
            "properties": {
              "host": {
                "type": "string"
              },
              "port": {
                "type": "integer"
              },
              "user": {
                "type": "string"
              },
              "password": {
                "type": "string"
              }
            }
          },
          "api_url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "description": "Public HTTPS endpoint for templates with an API"
          },
          "failure_reason": {
            "type": [
              "string",
              "null"
            ],
            "description": "Why provisioning failed (failed instances are not charged)"
          },
          "limits": {
            "$ref": "#/components/schemas/Limits"
          }
        }
      },
      "QuoteCandidate": {
        "type": "object",
        "properties": {
          "gpu_model": {
            "type": "string"
          },
          "vram_gb": {
            "type": [
              "integer",
              "null"
            ]
          },
          "gpu_count": {
            "type": "integer"
          },
          "disk_gb": {
            "type": [
              "integer",
              "null"
            ]
          },
          "price_per_gpu_hour_usd": {
            "type": "number"
          },
          "disk_addon_per_hour_usd": {
            "type": "number"
          },
          "instance_price_per_hour_usd": {
            "type": "number"
          },
          "billed_minutes": {
            "type": "integer"
          },
          "availability": {
            "enum": [
              "available",
              "limited",
              "unavailable"
            ]
          },
          "within_budget": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Whether estimated_total_cost is within max_budget_usd. Does not mean you can start now."
          },
          "estimated_total_cost": {
            "type": "number",
            "description": "USD the task is expected to use (billed minutes × instance price)."
          },
          "required_starting_balance": {
            "type": "number",
            "description": "USD balance needed to start: one hour is pre-authorised at start and unused minutes are refunded when the instance is destroyed. Usually higher than estimated_total_cost for short tasks."
          },
          "can_start_with_balance": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Only set when the request carries an API key: whether that account's balance covers required_starting_balance. null for anonymous requests."
          },
          "supports_jobs": {
            "type": "boolean",
            "description": "Whether this GPU can run a job with POST /v1/jobs right now. Some GPUs can only be rented as instances."
          }
        }
      },
      "Quote": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "quote_3f2b..."
          },
          "object": {
            "const": "compute.quote"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          },
          "currency": {
            "const": "USD"
          },
          "price_guarantee": {
            "const": "estimate"
          },
          "requires_authorization": {
            "type": "boolean"
          },
          "request": {
            "type": "object"
          },
          "billing": {
            "type": "object"
          },
          "candidates": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/QuoteCandidate"
            }
          },
          "within_budget": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "notes": {
            "type": "string"
          },
          "no_match_reason": {
            "type": "string"
          },
          "account": {
            "type": "object",
            "properties": {
              "authenticated": {
                "type": "boolean"
              },
              "balance_usd": {
                "type": [
                  "number",
                  "null"
                ]
              }
            }
          }
        }
      },
      "JobRequest": {
        "type": "object",
        "required": [
          "command",
          "max_minutes",
          "max_spend_usd"
        ],
        "properties": {
          "command": {
            "type": "string",
            "maxLength": 32768,
            "description": "Bash command run once on the GPU. If the live automatic_output_collection capability is true, declare outputs and write those files under $CLOUDGPU_OUTPUT_DIR. Otherwise save results explicitly before release."
          },
          "gpu_model": {
            "type": "string"
          },
          "template": {
            "type": "string"
          },
          "gpu_count": {
            "type": "integer",
            "minimum": 1,
            "maximum": 8
          },
          "disk_gb": {
            "type": "integer",
            "description": "Optional larger system disk, one of the catalog's disk_options"
          },
          "max_minutes": {
            "type": "integer",
            "minimum": 1,
            "description": "Time limit for the whole job, enforced by the server"
          },
          "max_spend_usd": {
            "type": "number",
            "description": "Spend limit for the whole job, enforced by the server"
          },
          "quote_id": {
            "type": "string",
            "description": "Optional; binds the job to a quote like POST /v1/gpu/instances does"
          },
          "workspace_version_id": {
            "type": "string",
            "pattern": "^wsv_[0-9a-f]{32}$",
            "description": "Optional immutable Workspace version, restored into a fresh project directory before the command. Requires enabled storage. Does not save changed files automatically or restore a boot disk."
          },
          "model_references": {
            "type": "array",
            "maxItems": 4,
            "items": {
              "$ref": "#/components/schemas/ModelReference"
            },
            "description": "Pinned public files, at most 100 GB across all references. Downloads go directly to the rented GPU after Workspace restore and consume the same time/spend limits. No platform model cache, dependency install or remote repository code execution."
          },
          "outputs": {
            "$ref": "#/components/schemas/JobOutputs"
          }
        },
        "description": "Give gpu_model, template or quote_id."
      },
      "Job": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "job_0123456789abcdef0123456789abcdef"
          },
          "object": {
            "type": "string",
            "enum": [
              "job"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "queued",
              "provisioning",
              "running",
              "stopping",
              "succeeded",
              "failed",
              "cancelled",
              "needs_attention"
            ],
            "description": "needs_attention: CloudGPU stopped the job because it could not confirm the state of its GPU, and will not retry it automatically."
          },
          "gpu_model": {
            "type": "string"
          },
          "gpu_count": {
            "type": "integer"
          },
          "template": {
            "type": "string",
            "nullable": true
          },
          "disk_gb": {
            "type": "integer"
          },
          "max_minutes": {
            "type": "integer"
          },
          "max_spend_usd": {
            "type": "number"
          },
          "instance_id": {
            "type": "string",
            "nullable": true,
            "description": "The GPU instance this job runs on; also readable with GET /v1/gpu/instances/{id}"
          },
          "attempt": {
            "type": "integer"
          },
          "cancel_requested": {
            "type": "boolean"
          },
          "exit_code": {
            "type": "integer",
            "nullable": true
          },
          "cost_usd": {
            "type": "number",
            "nullable": true
          },
          "error": {
            "type": "object",
            "nullable": true,
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            }
          },
          "created_at": {
            "type": "integer"
          },
          "started_at": {
            "type": "integer",
            "nullable": true
          },
          "finished_at": {
            "type": "integer",
            "nullable": true
          },
          "updated_at": {
            "type": "integer"
          },
          "workspace_version_id": {
            "type": "string",
            "nullable": true
          },
          "model_references": {
            "type": "array",
            "maxItems": 4,
            "items": {
              "$ref": "#/components/schemas/ModelReference"
            },
            "description": "Pinned public files, at most 100 GB across all references. Downloads go directly to the rented GPU after Workspace restore and consume the same time/spend limits. No platform model cache, dependency install or remote repository code execution."
          },
          "outputs": {
            "$ref": "#/components/schemas/JobOutputs"
          },
          "output_collection": {
            "$ref": "#/components/schemas/JobOutputCollection"
          }
        }
      },
      "ModelFile": {
        "type": "object",
        "required": [
          "path",
          "size_bytes"
        ],
        "additionalProperties": false,
        "properties": {
          "path": {
            "type": "string",
            "maxLength": 240,
            "description": "Explicit relative path; no empty, dot or parent segments."
          },
          "size_bytes": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100000000000
          },
          "sha256": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}$",
            "description": "Independently verified SHA-256; required when using an instance mirror."
          }
        }
      },
      "ModelReference": {
        "type": "object",
        "required": [
          "name",
          "repo_id",
          "revision",
          "files"
        ],
        "additionalProperties": false,
        "properties": {
          "name": {
            "type": "string",
            "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,47}$"
          },
          "repo_id": {
            "type": "string",
            "description": "Public Hugging Face owner/repo; no URL, token or private/gated repository."
          },
          "revision": {
            "type": "string",
            "pattern": "^[0-9a-f]{40}$"
          },
          "files": {
            "type": "array",
            "minItems": 1,
            "maxItems": 32,
            "items": {
              "$ref": "#/components/schemas/ModelFile"
            }
          }
        }
      },
      "JobRerunSpec": {
        "type": "object",
        "description": "Successful owned Job parameters only. No GPU starts. Obtain a fresh quote and approval, then use a new Idempotency-Key for a new task; no old quote/key is returned.",
        "properties": {
          "command": {
            "type": "string"
          },
          "model_references": {
            "type": "array",
            "maxItems": 4,
            "items": {
              "$ref": "#/components/schemas/ModelReference"
            },
            "description": "Pinned public files, at most 100 GB across all references. Downloads go directly to the rented GPU after Workspace restore and consume the same time/spend limits. No platform model cache, dependency install or remote repository code execution."
          },
          "workspace_version_id": {
            "type": "string"
          },
          "outputs": {
            "$ref": "#/components/schemas/JobOutputs"
          }
        }
      },
      "JobOutputs": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "files"
        ],
        "properties": {
          "files": {
            "type": "array",
            "minItems": 1,
            "maxItems": 16,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "maxLength": 512
            },
            "description": "Explicit relative regular files under $CLOUDGPU_OUTPUT_DIR. No globs, hidden/credential names, symlinks, hardlinks or device files."
          },
          "max_bytes": {
            "type": "integer",
            "minimum": 1,
            "maximum": 104857600,
            "default": 10485760,
            "description": "Total transfer limit, not an extra storage allowance."
          },
          "accept_storage_charges": {
            "type": "boolean",
            "default": false,
            "description": "Only after explicit agreement to existing paid storage terms. Budget-limited Agent keys cannot consent to paid storage."
          }
        },
        "nullable": true
      },
      "JobOutputCollection": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "collecting",
              "succeeded",
              "failed",
              "skipped"
            ]
          },
          "code": {
            "type": "string"
          },
          "cleanup_pending": {
            "type": "integer",
            "minimum": 0,
            "description": "Last collection attempt, not a live counter."
          },
          "files": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "path": {
                  "type": "string"
                },
                "file_id": {
                  "type": "string"
                },
                "sha256": {
                  "type": "string",
                  "pattern": "^[0-9a-f]{64}$"
                },
                "size_bytes": {
                  "type": "integer",
                  "minimum": 0
                },
                "status": {
                  "type": "string",
                  "enum": [
                    "uploading",
                    "ready",
                    "deleted",
                    "cleanup_pending"
                  ]
                }
              }
            }
          }
        },
        "description": "Only succeeded confirms all requested results are stored. Ready partial files may be downloaded with existing storage APIs. Collection failure does not prevent GPU release or trigger a retry. No signed URLs are returned.",
        "nullable": true
      }
    }
  }
}
