{
  "openapi": "3.1.0",
  "info": {
    "title": "CloudGPU API",
    "version": "1.8.0",
    "summary": "Compute infrastructure for AI agents: source-specific GPU billing and a model API.",
    "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 mounted persistent disks are not supported. Automatic output collection is available only when advertised by compute-capabilities, with explicit outputs and the published size/connectivity limits. Regional observations at /v1/public/compute-offers are planning facts, not region-bound quotes or allocations; unsupported hard placement is rejected before a new rental or Job.",
    "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. Integrated compatible supply is admitted from current stock and cost/funding checks, without a manual per-SKU physical-test allowlist. The model-level rate is a starting per-card rate; configurations carry whole-instance rates and native observation times. No measured delivery-time or latency promise is implied.",
        "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."
                  },
                  "continent": {
                    "type": "string",
                    "enum": [
                      "asia",
                      "europe",
                      "north_america",
                      "oceania",
                      "south_america",
                      "africa"
                    ],
                    "description": "Hard continent constraint, only when rental-regions.enabled is true. Must match the accepted billing quote. No country/datacenter selection or cross-continent fallback."
                  },
                  "billing_quote_id": {
                    "type": "string",
                    "description": "Exact identifier returned by POST /v1/gpu/billing-quote. Required for continent constraints and whole-hour sources."
                  },
                  "billing_accepted": {
                    "type": "boolean",
                    "description": "Explicit approval of this quote and its minimum billing charge."
                  }
                }
              },
              "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 published GPU SKU references, VRAM, availability, templates and disk options without spending. Final source-specific minute/started-hour minimums, increments and required starting balance come from a fresh quote. The catalogue does not reserve stock or bind a location.",
        "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
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/public/compute-offers": {
      "get": {
        "tags": [
          "Agent Compute"
        ],
        "operationId": "listRegionalComputeObservations",
        "summary": "Read native regional compute observations without login or spending",
        "description": "Check regional_offer_discovery in compute-capabilities. Inventory and source-price evidence expire independently. Historical measured costs are not current quotes. Published SKU references are not regional retail quotes. This release cannot allocate an exact location or activate dynamic regional retail. Do not submit a hard location requirement through an ordinary quote/rental/Job. Unknown CPU/RAM/disk/image/topology/network/cost facts stay unknown; known pool aliases cannot be summed into a global independent total.",
        "security": [],
        "parameters": [
          {
            "name": "user_country",
            "in": "query",
            "required": false,
            "description": "Human owner's explicit ISO country; never the Agent server IP.",
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z]{2}$"
            }
          },
          {
            "name": "country_code",
            "in": "query",
            "required": false,
            "description": "Filter only explicitly verified country mappings.",
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z]{2}$"
            }
          },
          {
            "name": "gpu_model",
            "in": "query",
            "required": false,
            "description": "Canonical GPU model or supported alias.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "gpu_count",
            "in": "query",
            "required": false,
            "description": "Requested count; observed cards do not certify single-host multi-GPU placement.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 8,
              "default": 1
            }
          },
          {
            "name": "include_unavailable",
            "in": "query",
            "required": false,
            "description": "Include stale, failed, zero or unobserved facts without treating them as available.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Page size, 1–200; default 100.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 100
            }
          },
          {
            "name": "after_id",
            "in": "query",
            "required": false,
            "description": "Use next_after_id from the prior response; paging is a live non-atomic view.",
            "schema": {
              "type": "string",
              "pattern": "^offer_[a-f0-9]{32}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Planning observations only; not a reservation or allocation authorization",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "schema_version",
                    "read_only",
                    "execution_supported",
                    "offers",
                    "coverage"
                  ],
                  "properties": {
                    "schema_version": {
                      "const": "regional-offers/1"
                    },
                    "enabled": {
                      "type": "boolean"
                    },
                    "read_only": {
                      "const": true
                    },
                    "execution_supported": {
                      "const": false
                    },
                    "provider_requests_started": {
                      "const": false
                    },
                    "creates_charges": {
                      "const": false
                    },
                    "generated_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "offers": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/RegionalComputeObservation"
                      }
                    },
                    "has_more": {
                      "type": "boolean"
                    },
                    "next_after_id": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "pagination_consistency": {
                      "type": "string"
                    },
                    "capacity_totals_additive": {
                      "const": false
                    },
                    "global_coverage_verified": {
                      "const": false
                    },
                    "coverage": {
                      "type": "object",
                      "description": "Observed subset only; missing data does not prove global stockout and no independent global GPU total is asserted."
                    },
                    "recommendation": {
                      "type": "object",
                      "description": "Explicit country match only; no latency measurement or task decision."
                    },
                    "standard_quotes_accept_exact_region": {
                      "const": false
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid filter or cursor"
          },
          "429": {
            "description": "Discovery request limit exceeded"
          },
          "503": {
            "description": "Observation storage unavailable; not evidence of zero stock"
          }
        }
      }
    },
    "/v1/public/rental-regions": {
      "get": {
        "summary": "Qualified continent rental catalog",
        "security": [],
        "description": "Read-only; no supplier request or allocation. Check enabled before using continent-constrained rentals. generatedAt is response generation time, not the native observation time. Unqualified suppliers never gain a continent from IP or naming heuristics.",
        "parameters": [
          {
            "name": "continent",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "asia",
                "europe",
                "north_america",
                "oceania",
                "south_america",
                "africa"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "enabled, continents, defaultContinent, selected continent, generatedAt, inventory, capability matrix and verified count matrix"
          },
          "400": {
            "description": "Invalid continent"
          },
          "503": {
            "description": "Catalog unavailable; never fall back across continents"
          }
        }
      }
    },
    "/v1/gpu/billing-quote": {
      "post": {
        "summary": "Obtain a user-bound rental billing quote",
        "description": "Does not create or charge a GPU. Quote expires after five minutes; explicit region, model, count, environment and disk selections are bound. Country/individual datacenter constraints are rejected.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "gpuModel",
                  "gpuCount"
                ],
                "properties": {
                  "gpuModel": {
                    "type": "string"
                  },
                  "gpuCount": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 8
                  },
                  "templateId": {
                    "type": "string"
                  },
                  "modelName": {
                    "type": "string"
                  },
                  "diskGb": {
                    "type": "integer",
                    "minimum": 0
                  },
                  "continent": {
                    "type": "string",
                    "enum": [
                      "asia",
                      "europe",
                      "north_america",
                      "oceania",
                      "south_america",
                      "africa"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "billingQuoteId, gpuModel, gpuCount, continent, currency, incrementSeconds, minimumSeconds, minimumChargeUsd, hourlyTotalUsd, preauthorizedUsd, expiresAt (epoch milliseconds)"
          },
          "409": {
            "description": "No verified quote for this exact selection"
          }
        }
      }
    }
  },
  "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"
          },
          "inventory_count_exact": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "False means configuration availability, not an exact count of physical GPUs or machines."
          },
          "configurations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ComputeConfiguration"
            }
          }
        }
      },
      "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
      },
      "RegionalComputeObservation": {
        "type": "object",
        "required": [
          "offer_id",
          "gpu_model",
          "location",
          "inventory",
          "pricing",
          "discovery_only",
          "execution_supported"
        ],
        "properties": {
          "offer_id": {
            "type": "string",
            "pattern": "^offer_[a-f0-9]{32}$",
            "description": "Opaque discovery identity; cannot authorize a purchase."
          },
          "gpu_model": {
            "type": "string"
          },
          "vram_gb": {
            "type": [
              "integer",
              "null"
            ]
          },
          "configuration_revision": {
            "type": "string",
            "description": "Revision of disclosed discovery metadata only, not an executable immutable configuration."
          },
          "location": {
            "type": "object",
            "properties": {
              "id": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "country_code": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "label": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "precision": {
                "type": "string"
              }
            }
          },
          "inventory": {
            "type": "object",
            "properties": {
              "state": {
                "type": "string"
              },
              "available_cards": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "last_reported_cards": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "observed_at": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "expires_at": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "stock_reserved": {
                "const": false
              },
              "single_host_multi_gpu_count_verified": {
                "const": false
              },
              "capacity_group_id": {
                "type": "string"
              }
            }
          },
          "pricing": {
            "type": "object",
            "description": "Source evidence state is independent of inventory. Private procurement is omitted. A published SKU reference is not region bound.",
            "properties": {
              "state": {
                "type": "string"
              },
              "evidence": {
                "type": "string"
              },
              "observed_at": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "expires_at": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "regional_retail_quote_available": {
                "const": false
              },
              "bounded_total_usd": {
                "type": "null"
              },
              "published_sku_reference_usd_per_gpu_hour": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "reference_is_region_bound": {
                "const": false
              }
            }
          },
          "billing": {
            "type": "object",
            "description": "Source-specific billing reference only; a fresh executable quote is still required."
          },
          "capabilities": {
            "type": "object",
            "description": "Unqualified capability facts are explicitly null; Workspace is explicit R2 snapshots and restore."
          },
          "discovery_only": {
            "const": true
          },
          "execution_supported": {
            "const": false
          },
          "reservation_supported": {
            "const": false
          }
        }
      },
      "ComputeConfiguration": {
        "type": "object",
        "description": "Optional normalized native configuration facts. Missing/null values are unknown. Overlapping host sizes must not be summed as a fleet count. Image and Job support are separate capabilities.",
        "properties": {
          "gpuCount": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Unknown values are null; metadata applies to this entire single-host configuration."
          },
          "vramPerGpuGb": {
            "type": [
              "integer",
              "null"
            ],
            "description": "VRAM in GB per GPU, not summed across the host."
          },
          "vcpu": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Unknown values are null; metadata applies to this entire single-host configuration."
          },
          "memoryGb": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Unknown values are null; metadata applies to this entire single-host configuration."
          },
          "systemDiskGb": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Unknown values are null; metadata applies to this entire single-host configuration."
          },
          "localDiskGb": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Unknown values are null; metadata applies to this entire single-host configuration."
          },
          "region": {
            "type": [
              "string",
              "null"
            ]
          },
          "interconnect": {
            "type": [
              "string",
              "null"
            ]
          },
          "available": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "confidentialCompute": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "hourlyPrice": {
            "type": [
              "number",
              "string",
              "null"
            ],
            "description": "USD per hour for the whole instance with gpuCount GPUs, not a per-card rate. Obtain an exact billing quote before allocation."
          },
          "minimumBillingSeconds": {
            "type": [
              "integer",
              "null"
            ]
          },
          "billingIncrementSeconds": {
            "type": [
              "integer",
              "null"
            ]
          },
          "observedAt": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Source observation time in Unix milliseconds; not a reservation or delivery SLA."
          }
        }
      }
    }
  }
}
