{
  "openapi": "3.1.0",
  "info": {
    "title": "kosa8 Cloud API",
    "version": "1",
    "description": "Sealed sandboxes (microVMs) for AI agents and code, on kosa8's hosts or your own, billed per second. Authenticate with an API key from https://app.kosa8.com/app#keys as `Authorization: Bearer k8c_live_…`. Errors are `{error, message}` with a stable `error` code; a 402 also carries `upgrade_url` and `agent_message`. AI agents can also use the MCP server at POST /mcp (Streamable HTTP, same key). Guide: https://docs.kosa8.com/guides/cloud/",
    "contact": {
      "name": "kosa8",
      "url": "https://kosa8.com",
      "email": "contact@kosa8.com"
    }
  },
  "servers": [
    {
      "url": "https://api.kosa8.com"
    }
  ],
  "externalDocs": {
    "url": "https://docs.kosa8.com/guides/cloud-openapi/"
  },
  "security": [
    {
      "apiKey": []
    }
  ],
  "tags": [
    {
      "name": "Sandboxes"
    },
    {
      "name": "Sandbox files"
    },
    {
      "name": "Checkpoints"
    },
    {
      "name": "Snapshots"
    },
    {
      "name": "Machines"
    },
    {
      "name": "Account"
    },
    {
      "name": "Sign-in"
    },
    {
      "name": "API keys"
    },
    {
      "name": "Billing"
    },
    {
      "name": "Functions"
    },
    {
      "name": "Own hosts"
    },
    {
      "name": "Team"
    },
    {
      "name": "Audit"
    },
    {
      "name": "Security"
    },
    {
      "name": "Attack tests"
    },
    {
      "name": "Webhooks"
    },
    {
      "name": "Integrations"
    },
    {
      "name": "Store"
    },
    {
      "name": "Previews"
    },
    {
      "name": "Egress"
    },
    {
      "name": "Threat feed"
    },
    {
      "name": "Swarms"
    },
    {
      "name": "Secrets"
    },
    {
      "name": "Terminal and large files"
    },
    {
      "name": "Observability"
    },
    {
      "name": "Schedules"
    },
    {
      "name": "Code interpreter"
    },
    {
      "name": "Pipelines"
    }
  ],
  "paths": {
    "/v1/me": {
      "get": {
        "operationId": "getMe",
        "summary": "The organization and the calling key",
        "tags": [
          "Account"
        ],
        "x-kosa8-scope": "any",
        "description": "Any valid key.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      },
      "patch": {
        "operationId": "patchMe",
        "summary": "Change your display name (a member's session or key; an org key gets 409 member_required)",
        "tags": [
          "Account"
        ],
        "x-kosa8-scope": "any",
        "description": "Any valid key.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 100
                  }
                },
                "required": [
                  "name"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          }
        }
      }
    },
    "/v1/me/profile": {
      "get": {
        "operationId": "getProfile",
        "summary": "Your profile: name, email, role, how you sign in, newsletter",
        "tags": [
          "Account"
        ],
        "x-kosa8-scope": "any",
        "description": "Any valid key.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          }
        }
      }
    },
    "/v1/me/password": {
      "post": {
        "operationId": "changePassword",
        "summary": "Change your password; ends your sessions in other browsers and returns a fresh cookie",
        "tags": [
          "Account"
        ],
        "x-kosa8-scope": "any",
        "description": "Any valid key. Dashboard session only, never an API key. Five wrong current passwords in 15 minutes answer 429.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "current_password": {
                    "type": "string"
                  },
                  "new_password": {
                    "type": "string",
                    "minLength": 10,
                    "maxLength": 256
                  },
                  "sign_out_keys": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "current_password",
                  "new_password"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          }
        }
      }
    },
    "/v1/me/sign-out-others": {
      "post": {
        "operationId": "signOutOthers",
        "summary": "End your dashboard sessions in every other browser",
        "tags": [
          "Account"
        ],
        "x-kosa8-scope": "any",
        "description": "Any valid key. Dashboard session only.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          }
        }
      }
    },
    "/v1/me/sessions": {
      "get": {
        "operationId": "mySessions",
        "summary": "Your live CLI, desktop app and personal key sign-ins; revoke one with DELETE /v1/api-keys/{id}",
        "tags": [
          "Account"
        ],
        "x-kosa8-scope": "any",
        "description": "Any valid key.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          }
        }
      }
    },
    "/v1/me/newsletter": {
      "post": {
        "operationId": "setNewsletter",
        "summary": "Subscribe to or leave the kosa8 weekly",
        "tags": [
          "Account"
        ],
        "x-kosa8-scope": "any",
        "description": "Any valid key.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "subscribed": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "subscribed"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          },
          "503": {
            "$ref": "#/components/responses/E503"
          }
        }
      }
    },
    "/v1/pricing": {
      "get": {
        "operationId": "getPricing",
        "summary": "The rate card",
        "tags": [
          "Account"
        ],
        "security": [],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          }
        }
      }
    },
    "/v1/signup": {
      "get": {
        "operationId": "getSignupConfig",
        "summary": "Whether self-serve sign-up is open",
        "tags": [
          "Account"
        ],
        "security": [],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "signup",
        "summary": "Create an organization (the dashboard's sign-up form)",
        "tags": [
          "Account"
        ],
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          }
        }
      }
    },
    "/v1/auth/device": {
      "post": {
        "operationId": "startDeviceSignIn",
        "summary": "Start a browser sign-in for the CLI or desktop app (device authorization, RFC 8628)",
        "tags": [
          "Sign-in"
        ],
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "client": {
                    "type": "string",
                    "enum": [
                      "cli",
                      "desktop"
                    ]
                  },
                  "name": {
                    "type": "string",
                    "maxLength": 64,
                    "description": "This computer's hostname"
                  },
                  "source": {
                    "type": "string",
                    "enum": [
                      "cli_hint",
                      "cli_cloud"
                    ],
                    "description": "Optional: what started the sign-in (the kosa8 CLI sets it); recorded as a new org's sign-up source"
                  }
                },
                "required": [
                  "client",
                  "name"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeviceStart"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          }
        }
      }
    },
    "/v1/cli-events": {
      "post": {
        "operationId": "recordCliEvent",
        "summary": "The kosa8 CLI reports a Cloud hint shown or a --cloud handoff (anonymous; a key, if sent, adds the org). Allowed names and values only, body at most 512 bytes, rate-limited per network",
        "tags": [
          "Sign-in"
        ],
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "enum": [
                      "cloud_hint_shown",
                      "cloud_handoff",
                      "cloud_handoff_login"
                    ]
                  },
                  "reason": {
                    "type": "string",
                    "enum": [
                      "gpu",
                      "too_big",
                      "parallel",
                      "no_local",
                      "share"
                    ],
                    "description": "cloud_hint_shown: required; cloud_handoff: the hint that preceded it, if any"
                  },
                  "cmd": {
                    "type": "string",
                    "enum": [
                      "run",
                      "sandbox_create"
                    ],
                    "description": "cloud_handoff and cloud_handoff_login"
                  },
                  "stage": {
                    "type": "string",
                    "enum": [
                      "started",
                      "completed",
                      "failed"
                    ],
                    "description": "cloud_handoff_login"
                  },
                  "signed_in": {
                    "type": "boolean",
                    "description": "cloud_handoff: whether the CLI was already signed in"
                  },
                  "os": {
                    "type": "string"
                  },
                  "arch": {
                    "type": "string"
                  },
                  "version": {
                    "type": "string"
                  },
                  "install_id": {
                    "type": "string",
                    "pattern": "^i_[0-9a-f]{32}$",
                    "description": "A random per-install id; stored only as a keyed hash"
                  }
                },
                "required": [
                  "name",
                  "os",
                  "arch",
                  "version",
                  "install_id"
                ]
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Recorded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "413": {
            "$ref": "#/components/responses/E413"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          }
        }
      }
    },
    "/v1/auth/device/token": {
      "post": {
        "operationId": "redeemDeviceSignIn",
        "summary": "Poll for the sign-in's API key: 428 authorization_pending, 429 slow_down, 403 access_denied, 410 expired_token; 200 once, then 410",
        "tags": [
          "Sign-in"
        ],
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "device_code": {
                    "type": "string"
                  }
                },
                "required": [
                  "device_code"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "api_key": {
                      "type": "string",
                      "description": "k8c_live_…, shown once"
                    },
                    "org": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "name": {
                          "type": "string"
                        }
                      }
                    },
                    "email": {
                      "type": "string",
                      "description": "Who approved it"
                    },
                    "plan": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  },
                  "required": [
                    "api_key",
                    "org",
                    "email",
                    "plan"
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "410": {
            "$ref": "#/components/responses/E410"
          },
          "428": {
            "$ref": "#/components/responses/E428"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          }
        }
      }
    },
    "/v1/auth/device/pending": {
      "get": {
        "operationId": "getDeviceSignIn",
        "summary": "The sign-in a code belongs to (the /device page). Needs a person signed in to the dashboard, not an API key",
        "tags": [
          "Sign-in"
        ],
        "x-kosa8-scope": "any",
        "description": "Any valid key.",
        "parameters": [
          {
            "name": "user_code",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "ABCD-EFGH; any case, dash optional"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "410": {
            "$ref": "#/components/responses/E410"
          }
        }
      }
    },
    "/v1/auth/device/approve": {
      "post": {
        "operationId": "approveDeviceSignIn",
        "summary": "Approve: makes an API key named after the device for the approver. Dashboard session only",
        "tags": [
          "Sign-in"
        ],
        "x-kosa8-scope": "keys:manage",
        "description": "Needs the `keys:manage` scope (or one that includes it).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "user_code": {
                    "type": "string"
                  }
                },
                "required": [
                  "user_code"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "410": {
            "$ref": "#/components/responses/E410"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          }
        }
      }
    },
    "/v1/auth/device/deny": {
      "post": {
        "operationId": "denyDeviceSignIn",
        "summary": "Deny: the device's next poll gets 403 access_denied. Dashboard session only",
        "tags": [
          "Sign-in"
        ],
        "x-kosa8-scope": "any",
        "description": "Any valid key.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "user_code": {
                    "type": "string"
                  }
                },
                "required": [
                  "user_code"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "410": {
            "$ref": "#/components/responses/E410"
          }
        }
      }
    },
    "/v1/checkout/plan": {
      "get": {
        "operationId": "planCheckout",
        "summary": "Redirect to checkout for a plan",
        "tags": [
          "Billing"
        ],
        "security": [],
        "parameters": [
          {
            "name": "plan",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Plan key"
          }
        ],
        "responses": {
          "200": {
            "description": "Redirect"
          }
        }
      }
    },
    "/v1/settings": {
      "get": {
        "operationId": "getSettings",
        "summary": "Org settings",
        "tags": [
          "Account"
        ],
        "x-kosa8-scope": "sandboxes:read",
        "description": "Needs the `sandboxes:read` scope (or one that includes it).",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      },
      "patch": {
        "operationId": "patchSettings",
        "summary": "Change default_region, default_template, sleep_after_s, placement, spending_cap_usd",
        "tags": [
          "Account"
        ],
        "x-kosa8-scope": "admin",
        "description": "Needs the `admin` scope (or one that includes it).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "default_region": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "default_template": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "sleep_after_s": {
                    "type": "integer"
                  },
                  "placement": {
                    "type": "string",
                    "enum": [
                      "auto",
                      "own",
                      "shared"
                    ]
                  },
                  "spending_cap_usd": {
                    "type": [
                      "number",
                      "null"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      }
    },
    "/v1/api-keys": {
      "get": {
        "operationId": "listApiKeys",
        "summary": "List keys (never secrets)",
        "tags": [
          "API keys"
        ],
        "x-kosa8-scope": "keys:manage",
        "description": "Needs the `keys:manage` scope (or one that includes it).",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "api_keys": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ApiKey"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      },
      "post": {
        "operationId": "createApiKey",
        "summary": "Create a key; the secret is shown once",
        "tags": [
          "API keys"
        ],
        "x-kosa8-scope": "keys:manage",
        "description": "Needs the `keys:manage` scope (or one that includes it).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "scopes": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "expires_in_s": {
                    "type": "integer",
                    "minimum": 300,
                    "maximum": 31536000
                  }
                },
                "required": [
                  "name"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "api_key": {
                      "$ref": "#/components/schemas/ApiKey"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          }
        }
      }
    },
    "/v1/api-keys/{id}": {
      "delete": {
        "operationId": "revokeApiKey",
        "summary": "Revoke a key now",
        "tags": [
          "API keys"
        ],
        "x-kosa8-scope": "keys:manage",
        "description": "Needs the `keys:manage` scope (or one that includes it).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Id"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      }
    },
    "/v1/api-keys/{id}/rotate": {
      "post": {
        "operationId": "rotateApiKey",
        "summary": "New key with the same name and scopes; the old one lives grace_s more",
        "tags": [
          "API keys"
        ],
        "x-kosa8-scope": "keys:manage",
        "description": "Needs the `keys:manage` scope (or one that includes it).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Id"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "grace_s": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 86400
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "api_key": {
                      "$ref": "#/components/schemas/ApiKey"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          }
        }
      }
    },
    "/v1/gallery": {
      "get": {
        "operationId": "listGallery",
        "summary": "The Templates gallery: one-click starter sandboxes, each with its size, network, secrets, setup and first win (public, cacheable)",
        "tags": [
          "Sandboxes"
        ],
        "security": [],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "version": {
                      "type": "integer"
                    },
                    "egress": {
                      "type": "object",
                      "additionalProperties": true
                    },
                    "templates": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/gallery/{id}": {
      "get": {
        "operationId": "getGallery",
        "summary": "One gallery template (public)",
        "tags": [
          "Sandboxes"
        ],
        "security": [],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Gallery template id, e.g. claude-code"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "template": {
                      "type": "object",
                      "additionalProperties": true
                    },
                    "egress": {
                      "type": "object",
                      "additionalProperties": true
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      }
    },
    "/v1/gallery/{id}/launch": {
      "post": {
        "operationId": "launchGallery",
        "summary": "Launch a gallery template: create its sandbox with every setting it names and start its setup, detached",
        "tags": [
          "Sandboxes"
        ],
        "x-kosa8-scope": "sandboxes:write",
        "description": "Needs the `sandboxes:write` scope (or one that includes it). 409 secret_required names the secrets to store first with PUT /v1/secrets/{name}; a launch never carries a secret's value.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Gallery template id, e.g. claude-code"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "size": {
                    "type": "string",
                    "enum": [
                      "2x4",
                      "4x8",
                      "8x16",
                      "16x32"
                    ]
                  },
                  "region": {
                    "type": "string"
                  },
                  "ttl_s": {
                    "type": "integer"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Launched; poll progress",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "sandbox": {
                      "$ref": "#/components/schemas/Sandbox"
                    },
                    "gallery": {
                      "type": "object",
                      "additionalProperties": true
                    },
                    "setup": {
                      "type": "object",
                      "additionalProperties": true
                    },
                    "first_win": {
                      "type": "object",
                      "additionalProperties": true
                    },
                    "progress": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "402": {
            "$ref": "#/components/responses/E402"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          },
          "503": {
            "$ref": "#/components/responses/E503"
          }
        }
      }
    },
    "/v1/gallery/launches/{id}": {
      "post": {
        "operationId": "galleryLaunchProgress",
        "summary": "Where a gallery launch is (booting, setting_up, ready or failed); starts its setup once the sandbox is up",
        "tags": [
          "Sandboxes"
        ],
        "x-kosa8-scope": "sandboxes:write",
        "description": "Needs the `sandboxes:write` scope (or one that includes it).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Sandbox id (sbx_…)"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "state": {
                      "type": "string",
                      "enum": [
                        "booting",
                        "setting_up",
                        "ready",
                        "failed"
                      ]
                    },
                    "first_win": {
                      "type": "object",
                      "additionalProperties": true
                    },
                    "log_tail": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      }
    },
    "/v1/templates": {
      "get": {
        "operationId": "listTemplates",
        "summary": "Templates the org can create from now",
        "tags": [
          "Sandboxes"
        ],
        "x-kosa8-scope": "sandboxes:read",
        "description": "Needs the `sandboxes:read` scope (or one that includes it).",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "templates": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Template"
                      }
                    },
                    "default_template": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      }
    },
    "/v1/tour": {
      "get": {
        "operationId": "getTour",
        "summary": "Whether this member has finished the dashboard tour (member: false for an API-key session)",
        "tags": [
          "Account"
        ],
        "x-kosa8-scope": "any",
        "description": "Any valid key.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "member": {
                      "type": "boolean"
                    },
                    "done_at": {
                      "type": [
                        "integer",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      },
      "post": {
        "operationId": "setTour",
        "summary": "Mark the dashboard tour done or skipped, or reset it to show again",
        "tags": [
          "Account"
        ],
        "x-kosa8-scope": "any",
        "description": "Any valid key.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "action": {
                    "type": "string",
                    "enum": [
                      "done",
                      "skip",
                      "reset"
                    ]
                  }
                },
                "required": [
                  "action"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "member": {
                      "type": "boolean"
                    },
                    "done_at": {
                      "type": [
                        "integer",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          }
        }
      }
    },
    "/v1/overview": {
      "get": {
        "operationId": "getOverview",
        "summary": "Sandbox and function counts, this month's usage and credit, recent activity and host capacity",
        "tags": [
          "Machines"
        ],
        "x-kosa8-scope": "sandboxes:read",
        "description": "Needs the `sandboxes:read` scope (or one that includes it).",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "sandboxes": {
                      "type": "object",
                      "properties": {}
                    },
                    "functions": {
                      "type": [
                        "object",
                        "null"
                      ]
                    },
                    "month": {
                      "type": "object",
                      "properties": {}
                    },
                    "activity": {
                      "type": [
                        "array",
                        "null"
                      ]
                    },
                    "capacity": {
                      "type": "object",
                      "properties": {}
                    },
                    "capabilities": {
                      "type": "object",
                      "properties": {}
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      }
    },
    "/v1/overview/posture": {
      "get": {
        "operationId": "getOverviewPosture",
        "summary": "Secure, Safe and Sovereign posture scores from this org's own settings, the active fleet by state, region and template, the threat feed and swarm summary, 14 days of sandboxes started and sandbox-hours (trend), the home region and placement (place), and 14 days of audit activity with commands run (activity is null without audit:read). Reads the database only",
        "tags": [
          "Machines"
        ],
        "x-kosa8-scope": "sandboxes:read",
        "description": "Needs the `sandboxes:read` scope (or one that includes it).",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "at": {
                      "type": "integer"
                    },
                    "pillars": {
                      "type": "object",
                      "properties": {
                        "secure": {
                          "type": "object",
                          "properties": {}
                        },
                        "safe": {
                          "type": "object",
                          "properties": {}
                        },
                        "sovereign": {
                          "type": "object",
                          "properties": {}
                        }
                      }
                    },
                    "fleet": {
                      "type": "object",
                      "properties": {}
                    },
                    "guard": {
                      "type": "object",
                      "properties": {}
                    },
                    "trend": {
                      "type": "object",
                      "properties": {}
                    },
                    "place": {
                      "type": "object",
                      "properties": {}
                    },
                    "activity": {
                      "type": [
                        "object",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      }
    },
    "/v1/capabilities": {
      "get": {
        "operationId": "getCapabilities",
        "summary": "What this org's hosts can do: dataplane (checkpoints, rewind, fork, files), containers, custom images",
        "tags": [
          "Machines"
        ],
        "x-kosa8-scope": "sandboxes:read",
        "description": "Needs the `sandboxes:read` scope (or one that includes it).",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "dataplane": {
                      "type": "object",
                      "properties": {
                        "available": {
                          "type": "boolean"
                        },
                        "hosts": {
                          "type": "integer"
                        }
                      }
                    },
                    "containers": {
                      "type": "object",
                      "properties": {}
                    },
                    "custom_images": {
                      "type": "object",
                      "properties": {}
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      }
    },
    "/v1/lineage": {
      "get": {
        "operationId": "getLineage",
        "summary": "Sandboxes with their fork parents, for drawing the fork tree",
        "tags": [
          "Machines"
        ],
        "x-kosa8-scope": "sandboxes:read",
        "description": "Needs the `sandboxes:read` scope (or one that includes it).",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "nodes": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "parent_id": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "state": {
                            "type": "string"
                          },
                          "dataplane": {
                            "type": "boolean"
                          }
                        }
                      }
                    },
                    "roots": {
                      "type": "integer"
                    },
                    "forked": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      }
    },
    "/v1/checkpoints": {
      "get": {
        "operationId": "listOrgCheckpoints",
        "summary": "Checkpoints of every running or sleeping sandbox (up to 25), asked of each host; does not wake any",
        "tags": [
          "Checkpoints"
        ],
        "x-kosa8-scope": "sandboxes:read",
        "description": "Needs the `sandboxes:read` scope (or one that includes it).",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "dataplane": {
                      "type": "object",
                      "properties": {}
                    },
                    "sandboxes": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "dataplane": {
                            "type": "boolean"
                          },
                          "checkpoints": {
                            "type": [
                              "array",
                              "null"
                            ],
                            "items": {
                              "$ref": "#/components/schemas/Checkpoint"
                            }
                          }
                        }
                      }
                    },
                    "truncated": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      }
    },
    "/v1/images": {
      "get": {
        "operationId": "listImages",
        "summary": "Images behind the templates this org's hosts offer, with tag and digest when the reference names them",
        "tags": [
          "Machines"
        ],
        "x-kosa8-scope": "sandboxes:read",
        "description": "Needs the `sandboxes:read` scope (or one that includes it).",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "images": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "template": {
                            "type": "string"
                          },
                          "image": {
                            "type": "string"
                          },
                          "tag": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "digest": {
                            "type": [
                              "string",
                              "null"
                            ]
                          }
                        }
                      }
                    },
                    "custom_images": {
                      "type": "object",
                      "properties": {}
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      }
    },
    "/v1/sandboxes": {
      "get": {
        "operationId": "listSandboxes",
        "summary": "List sandboxes, newest first, a page at a time",
        "tags": [
          "Sandboxes"
        ],
        "x-kosa8-scope": "sandboxes:read",
        "description": "Needs the `sandboxes:read` scope (or one that includes it). When next_cursor is not null there are more: call again with cursor set to it.",
        "parameters": [
          {
            "name": "all",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ]
            },
            "description": "1 includes deleted ones"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500,
              "default": 500
            },
            "description": "Sandboxes per page (default and most: 500)"
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "next_cursor from the previous page"
          },
          {
            "name": "name",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "only sandboxes with this name"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "sandboxes": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Sandbox"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Pass as cursor for the next page; null on the last page"
                    }
                  },
                  "required": [
                    "sandboxes",
                    "next_cursor"
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      },
      "post": {
        "operationId": "createSandbox",
        "summary": "Create a sandbox",
        "tags": [
          "Sandboxes"
        ],
        "x-kosa8-scope": "sandboxes:write",
        "description": "Needs the `sandboxes:write` scope (or one that includes it). 201: it is running. 202: a sized or image create booting cold (state creating); poll GET /v1/sandboxes/{id} until running. 404: the snapshot or a named secret is not the org's. 409: a Store item's price changed (price_changed).",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SandboxCreate"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "sandbox": {
                      "$ref": "#/components/schemas/Sandbox"
                    },
                    "host_ms": {
                      "type": [
                        "integer",
                        "null"
                      ]
                    },
                    "direct": {
                      "$ref": "#/components/schemas/DirectExec"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "description": "Accepted: booting cold (state creating)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "sandbox": {
                      "$ref": "#/components/schemas/Sandbox"
                    },
                    "host_ms": {
                      "type": [
                        "integer",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "402": {
            "$ref": "#/components/responses/E402"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          },
          "501": {
            "$ref": "#/components/responses/E501"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          },
          "503": {
            "$ref": "#/components/responses/E503"
          }
        }
      }
    },
    "/v1/sandboxes/{id}": {
      "get": {
        "operationId": "getSandbox",
        "summary": "Get a sandbox",
        "tags": [
          "Sandboxes"
        ],
        "x-kosa8-scope": "sandboxes:read",
        "description": "Needs the `sandboxes:read` scope (or one that includes it).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Sandbox id (sbx_…)"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "sandbox": {
                      "$ref": "#/components/schemas/Sandbox"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      },
      "patch": {
        "operationId": "patchSandbox",
        "summary": "Change its lifetime or sleep timer",
        "tags": [
          "Sandboxes"
        ],
        "x-kosa8-scope": "sandboxes:write",
        "description": "Needs the `sandboxes:write` scope (or one that includes it).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Sandbox id (sbx_…)"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "ttl_s": {
                    "type": [
                      "integer",
                      "null"
                    ]
                  },
                  "delete_after": {
                    "type": [
                      "integer",
                      "null"
                    ]
                  },
                  "sleep_after_s": {
                    "type": "integer"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "sandbox": {
                      "$ref": "#/components/schemas/Sandbox"
                    },
                    "notes": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          }
        }
      },
      "delete": {
        "operationId": "deleteSandbox",
        "summary": "Delete a sandbox",
        "tags": [
          "Sandboxes"
        ],
        "x-kosa8-scope": "sandboxes:write",
        "description": "Needs the `sandboxes:write` scope (or one that includes it).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Sandbox id (sbx_…)"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      }
    },
    "/v1/sandboxes/{id}/exec": {
      "post": {
        "operationId": "execSandbox",
        "summary": "Run a command, or start one that keeps running (background: true); a sleeping sandbox wakes first",
        "tags": [
          "Sandboxes"
        ],
        "x-kosa8-scope": "sandboxes:write",
        "description": "Needs the `sandboxes:write` scope (or one that includes it). A buffered exec runs at most 90 s: past that the command is stopped and the answer is 504 exec_timeout. For longer commands send stream: true, which is not held to it, or background: true. Commands run in the sandbox's own long-lived container, whose filesystem lasts between commands; one naming another image runs in a fresh container that shares only /workspace. With background: true the answer is 202 at once and the command keeps running after the call (detached, its output to a workspace file): GET /v1/sandboxes/{id}/exec/{exec_id} reports it. Without it, a process the command leaves behind is not guaranteed to outlive it unless the sandbox is persistent. The sandbox's env from create is given to every command, the exec's own env winning per name.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Sandbox id (sbx_…)"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Exec"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExecResult"
                }
              }
            }
          },
          "202": {
            "description": "background: true: started, still running",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "exec": {
                      "$ref": "#/components/schemas/BackgroundExec"
                    },
                    "woke_ms": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "402": {
            "$ref": "#/components/responses/E402"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          },
          "501": {
            "$ref": "#/components/responses/E501"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          },
          "504": {
            "$ref": "#/components/responses/E504"
          }
        }
      }
    },
    "/v1/sandboxes/{id}/exec/{exec_id}": {
      "get": {
        "operationId": "getBackgroundExec",
        "summary": "A background command: running or exited, its exit code and its output so far",
        "tags": [
          "Sandboxes"
        ],
        "x-kosa8-scope": "sandboxes:read",
        "description": "Needs the `sandboxes:read` scope (or one that includes it). Reads its output file (the first MiB) and its exit file; a sleeping sandbox wakes first.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Sandbox id (sbx_…)"
          },
          {
            "name": "exec_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The id POST …/exec {background: true} answered (bg_…)"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "exec": {
                      "$ref": "#/components/schemas/BackgroundExec"
                    },
                    "woke_ms": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "402": {
            "$ref": "#/components/responses/E402"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "501": {
            "$ref": "#/components/responses/E501"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      }
    },
    "/v1/sandboxes/{id}/exec/{exec_id}/stop": {
      "post": {
        "operationId": "stopBackgroundExec",
        "summary": "Stop a background command and what it started (SIGTERM, then SIGKILL after 5 s)",
        "tags": [
          "Sandboxes"
        ],
        "x-kosa8-scope": "sandboxes:write",
        "description": "Needs the `sandboxes:write` scope (or one that includes it). exited: it had already ended. Its exit code (143 or 137 when stopped) and stopped: true come from GET …/exec/{exec_id}. 409 no_pid: started by an older host, end it with kill.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Sandbox id (sbx_…)"
          },
          {
            "name": "exec_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The background command's id (bg_…)"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "exec": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "sandbox_id": {
                          "type": "string"
                        },
                        "state": {
                          "type": "string",
                          "enum": [
                            "stopping",
                            "exited"
                          ]
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "402": {
            "$ref": "#/components/responses/E402"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          },
          "501": {
            "$ref": "#/components/responses/E501"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      }
    },
    "/v1/snapshots": {
      "get": {
        "operationId": "listSnapshots",
        "summary": "The org's snapshots, newest first",
        "tags": [
          "Snapshots"
        ],
        "x-kosa8-scope": "sandboxes:read",
        "description": "Needs the `sandboxes:read` scope (or one that includes it).",
        "parameters": [
          {
            "name": "sandbox_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Only those taken from this sandbox"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "snapshots": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Snapshot"
                      }
                    },
                    "max": {
                      "type": "integer",
                      "description": "How many the org may keep at once"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      }
    },
    "/v1/snapshots/{id}": {
      "get": {
        "operationId": "getSnapshot",
        "summary": "Get a snapshot",
        "tags": [
          "Snapshots"
        ],
        "x-kosa8-scope": "sandboxes:read",
        "description": "Needs the `sandboxes:read` scope (or one that includes it).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Snapshot id (snap_…)"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "snapshot": {
                      "$ref": "#/components/schemas/Snapshot"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      },
      "delete": {
        "operationId": "deleteSnapshot",
        "summary": "Delete a snapshot: its bytes leave its host and its storage stops being billed; sandboxes made from it are not touched",
        "tags": [
          "Snapshots"
        ],
        "x-kosa8-scope": "sandboxes:write",
        "description": "Needs the `sandboxes:write` scope (or one that includes it).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Snapshot id (snap_…)"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      }
    },
    "/v1/sandboxes/{id}/snapshots": {
      "post": {
        "operationId": "createSnapshot",
        "summary": "Save the sandbox as a snapshot of the org's: memory, processes and disk, kept until deleted, whatever happens to the sandbox",
        "tags": [
          "Snapshots"
        ],
        "x-kosa8-scope": "sandboxes:write",
        "description": "Needs the `sandboxes:write` scope (or one that includes it). The sandbox keeps running (a sleeping one is woken). Make sandboxes from it with POST /v1/sandboxes {\"snapshot\": id}; it outlives the sandbox it came from (unlike a checkpoint, which goes with its sandbox). Kept on the source's host, and sandboxes made from it run there. Billed as storage, $0.08 per GiB-month of its bytes, until deleted. At most 50 per org (429 snapshot_limit). Not for dedicated-cores sandboxes or ones with secrets (409).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Sandbox id (sbx_…)"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "snapshot": {
                      "$ref": "#/components/schemas/Snapshot"
                    },
                    "ms": {
                      "type": [
                        "integer",
                        "null"
                      ]
                    },
                    "woke_ms": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "402": {
            "$ref": "#/components/responses/E402"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          },
          "501": {
            "$ref": "#/components/responses/E501"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      }
    },
    "/v1/sandboxes/{id}/direct": {
      "post": {
        "operationId": "directSandbox",
        "summary": "A token to send this sandbox's commands to its host directly",
        "tags": [
          "Sandboxes"
        ],
        "x-kosa8-scope": "sandboxes:write",
        "description": "Needs the `sandboxes:write` scope (or one that includes it). Create answers with the same direct object. POST its exec_url with the body of /exec and Authorization: Bearer <token>: the command runs on the sandbox's host without passing through this API, and the answer is /exec's. The token works for exec on this sandbox only, until expires_at (5 minutes); ask here for a fresh one. A sleeping sandbox answers 409 use_api: send that command through /exec, which wakes it. Each command is still in the org's audit log, within seconds.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Sandbox id (sbx_…)"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "direct": {
                      "$ref": "#/components/schemas/DirectExec"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "501": {
            "$ref": "#/components/responses/E501"
          }
        }
      }
    },
    "/v1/sandboxes/{id}/sleep": {
      "post": {
        "operationId": "sleepSandbox",
        "summary": "Snapshot it and free its RAM",
        "tags": [
          "Sandboxes"
        ],
        "x-kosa8-scope": "sandboxes:write",
        "description": "Needs the `sandboxes:write` scope (or one that includes it).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Sandbox id (sbx_…)"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "sandbox": {
                      "$ref": "#/components/schemas/Sandbox"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      }
    },
    "/v1/sandboxes/{id}/wake": {
      "post": {
        "operationId": "wakeSandbox",
        "summary": "Restore a sleeping sandbox now",
        "tags": [
          "Sandboxes"
        ],
        "x-kosa8-scope": "sandboxes:write",
        "description": "Needs the `sandboxes:write` scope (or one that includes it).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Sandbox id (sbx_…)"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "sandbox": {
                      "$ref": "#/components/schemas/Sandbox"
                    },
                    "wake_ms": {
                      "type": [
                        "integer",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "402": {
            "$ref": "#/components/responses/E402"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          },
          "503": {
            "$ref": "#/components/responses/E503"
          }
        }
      }
    },
    "/v1/sandboxes/{id}/files": {
      "get": {
        "operationId": "readSandboxFile",
        "summary": "Download a file, streamed; a sleeping sandbox wakes first",
        "tags": [
          "Sandbox files"
        ],
        "x-kosa8-scope": "sandboxes:read",
        "description": "Needs the `sandboxes:read` scope (or one that includes it). The bytes stream between the caller and the sandbox, never held whole on the way, so a file has no size cap but the sandbox's disk (4 GiB a request). Any absolute path: /workspace, which lasts across sleep and snapshots, or anywhere else in the sandbox's container (/tmp, /root, /home/…), the filesystem its commands see.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Sandbox id (sbx_…)"
          },
          {
            "name": "path",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "An absolute path in the sandbox, e.g. /workspace/app.py, /tmp/out.bin or /root/.bashrc (a relative path is relative to /workspace; no ..)"
          },
          {
            "name": "Range",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "One byte range, bytes=a-b, a- or -n: the answer is 206 with Content-Range, or 416 past the end"
          }
        ],
        "responses": {
          "200": {
            "description": "The file's bytes (206 with Content-Range for a Range)",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "402": {
            "$ref": "#/components/responses/E402"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "413": {
            "$ref": "#/components/responses/E413"
          },
          "416": {
            "$ref": "#/components/responses/E416"
          },
          "501": {
            "$ref": "#/components/responses/E501"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      },
      "put": {
        "operationId": "writeSandboxFile",
        "summary": "Upload a file (the body, any bytes), streamed",
        "tags": [
          "Sandbox files"
        ],
        "x-kosa8-scope": "sandboxes:write",
        "description": "Needs the `sandboxes:write` scope (or one that includes it). The bytes stream between the caller and the sandbox, never held whole on the way, so a file has no size cap but the sandbox's disk (4 GiB a request). Any absolute path: /workspace, which lasts across sleep and snapshots, or anywhere else in the sandbox's container (/tmp, /root, /home/…), the filesystem its commands see. Through this API one request body is at most 100 MB (Cloudflare's limit): send a bigger file in parts with offset=, or PUT it to the direct files_url (POST …/direct) or a PUT link (POST …/files/link), which go to the host straight.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Sandbox id (sbx_…)"
          },
          {
            "name": "path",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "An absolute path in the sandbox, e.g. /workspace/app.py, /tmp/out.bin or /root/.bashrc (a relative path is relative to /workspace; no ..)"
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0
            },
            "description": "Write the body at this byte, keeping the rest of the file and growing it as needed: parts of a big upload, in any order or in parallel"
          },
          {
            "name": "append",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "1",
                "true"
              ]
            },
            "description": "Add the body at the end of the file (not with offset)"
          },
          {
            "name": "mode",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[0-7]{3,4}$"
            },
            "description": "Permission bits, octal, e.g. 755"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/octet-stream": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "file": {
                      "$ref": "#/components/schemas/FileInfo"
                    },
                    "woke_ms": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "402": {
            "$ref": "#/components/responses/E402"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "413": {
            "$ref": "#/components/responses/E413"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          },
          "501": {
            "$ref": "#/components/responses/E501"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          },
          "507": {
            "$ref": "#/components/responses/E507"
          }
        }
      },
      "delete": {
        "operationId": "deleteSandboxFile",
        "summary": "Remove a file, or a folder with recursive=1",
        "tags": [
          "Sandbox files"
        ],
        "x-kosa8-scope": "sandboxes:write",
        "description": "Needs the `sandboxes:write` scope (or one that includes it).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Sandbox id (sbx_…)"
          },
          {
            "name": "path",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "An absolute path in the sandbox, e.g. /workspace/app.py, /tmp/out.bin or /root/.bashrc (a relative path is relative to /workspace; no ..)"
          },
          {
            "name": "recursive",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "1",
                "true"
              ]
            },
            "description": "Remove a folder and everything in it"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "removed": {
                      "type": "string"
                    },
                    "woke_ms": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "402": {
            "$ref": "#/components/responses/E402"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          },
          "501": {
            "$ref": "#/components/responses/E501"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      }
    },
    "/v1/sandboxes/{id}/files/list": {
      "get": {
        "operationId": "listSandboxFiles",
        "summary": "List a folder (default /workspace)",
        "tags": [
          "Sandbox files"
        ],
        "x-kosa8-scope": "sandboxes:read",
        "description": "Needs the `sandboxes:read` scope (or one that includes it).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Sandbox id (sbx_…)"
          },
          {
            "name": "path",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Folder; default /workspace"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "path": {
                      "type": "string"
                    },
                    "files": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/FileInfo"
                      }
                    },
                    "woke_ms": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "402": {
            "$ref": "#/components/responses/E402"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "501": {
            "$ref": "#/components/responses/E501"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      }
    },
    "/v1/sandboxes/{id}/files/mkdir": {
      "post": {
        "operationId": "makeSandboxDir",
        "summary": "Make a folder (and its parents)",
        "tags": [
          "Sandbox files"
        ],
        "x-kosa8-scope": "sandboxes:write",
        "description": "Needs the `sandboxes:write` scope (or one that includes it).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Sandbox id (sbx_…)"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "path": {
                    "type": "string"
                  }
                },
                "required": [
                  "path"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "file": {
                      "$ref": "#/components/schemas/FileInfo"
                    },
                    "woke_ms": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "402": {
            "$ref": "#/components/responses/E402"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          },
          "501": {
            "$ref": "#/components/responses/E501"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      }
    },
    "/v1/sandboxes/{id}/checkpoints": {
      "get": {
        "operationId": "listCheckpoints",
        "summary": "Checkpoints, oldest first; does not wake a sleeping sandbox",
        "tags": [
          "Checkpoints"
        ],
        "x-kosa8-scope": "sandboxes:read",
        "description": "Needs the `sandboxes:read` scope (or one that includes it).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Sandbox id (sbx_…)"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "checkpoints": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Checkpoint"
                      }
                    },
                    "max": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "501": {
            "$ref": "#/components/responses/E501"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      },
      "post": {
        "operationId": "createCheckpoint",
        "summary": "Save memory, processes and disk as a checkpoint; the newest 10 are kept",
        "tags": [
          "Checkpoints"
        ],
        "x-kosa8-scope": "sandboxes:write",
        "description": "Needs the `sandboxes:write` scope (or one that includes it).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Sandbox id (sbx_…)"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "label": {
                    "type": "string",
                    "maxLength": 200
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "checkpoint": {
                      "$ref": "#/components/schemas/Checkpoint"
                    },
                    "evicted": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "ms": {
                      "type": [
                        "integer",
                        "null"
                      ]
                    },
                    "woke_ms": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "402": {
            "$ref": "#/components/responses/E402"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          },
          "501": {
            "$ref": "#/components/responses/E501"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      }
    },
    "/v1/sandboxes/{id}/rewind": {
      "post": {
        "operationId": "rewindSandbox",
        "summary": "Go back to a checkpoint; the sandbox as it was is first saved as an automatic checkpoint (backup)",
        "tags": [
          "Checkpoints"
        ],
        "x-kosa8-scope": "sandboxes:write",
        "description": "Needs the `sandboxes:write` scope (or one that includes it).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Sandbox id (sbx_…)"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "checkpoint_id": {
                    "type": "string"
                  }
                },
                "required": [
                  "checkpoint_id"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "sandbox": {
                      "$ref": "#/components/schemas/Sandbox"
                    },
                    "checkpoint": {
                      "$ref": "#/components/schemas/Checkpoint"
                    },
                    "backup": {
                      "$ref": "#/components/schemas/Checkpoint"
                    },
                    "ms": {
                      "type": [
                        "integer",
                        "null"
                      ]
                    },
                    "woke_ms": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "402": {
            "$ref": "#/components/responses/E402"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          },
          "501": {
            "$ref": "#/components/responses/E501"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      }
    },
    "/v1/sandboxes/{id}/fork": {
      "post": {
        "operationId": "forkSandbox",
        "summary": "n copies of the sandbox as it is now, on its host; the rules of a create; all or nothing",
        "tags": [
          "Sandboxes"
        ],
        "x-kosa8-scope": "sandboxes:write",
        "description": "Needs the `sandboxes:write` scope (or one that includes it).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Sandbox id (sbx_…)"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "n": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 100
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "parent": {
                      "type": "string"
                    },
                    "sandboxes": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Sandbox"
                      }
                    },
                    "host_ms": {
                      "type": [
                        "integer",
                        "null"
                      ]
                    },
                    "woke_ms": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "402": {
            "$ref": "#/components/responses/E402"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          },
          "501": {
            "$ref": "#/components/responses/E501"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          },
          "503": {
            "$ref": "#/components/responses/E503"
          }
        }
      }
    },
    "/v1/sandboxes/{id}/ports": {
      "get": {
        "operationId": "listSandboxPorts",
        "summary": "TCP ports listening in its running containers",
        "tags": [
          "Sandboxes"
        ],
        "x-kosa8-scope": "sandboxes:read",
        "description": "Needs the `sandboxes:read` scope (or one that includes it).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Sandbox id (sbx_…)"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ports": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "port": {
                            "type": "integer"
                          },
                          "address": {
                            "type": "string"
                          },
                          "container": {
                            "type": "string"
                          },
                          "loopback": {
                            "type": "boolean"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "501": {
            "$ref": "#/components/responses/E501"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      }
    },
    "/v1/usage": {
      "get": {
        "operationId": "getUsage",
        "summary": "This month's bill so far",
        "tags": [
          "Billing"
        ],
        "x-kosa8-scope": "sandboxes:read",
        "description": "Needs the `sandboxes:read` scope (or one that includes it).",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Usage"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      }
    },
    "/v1/limits": {
      "get": {
        "operationId": "getLimits",
        "summary": "The running-sandbox limit: how many are active, the limit, and the last request for more",
        "tags": [
          "Billing"
        ],
        "x-kosa8-scope": "sandboxes:read",
        "description": "Needs the `sandboxes:read` scope (or one that includes it).",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "active": {
                      "type": "integer"
                    },
                    "max_running": {
                      "type": "integer"
                    },
                    "reached": {
                      "type": "boolean"
                    },
                    "counts": {
                      "type": "string"
                    },
                    "last_request": {
                      "type": [
                        "object",
                        "null"
                      ]
                    },
                    "request_url": {
                      "type": "string",
                      "format": "uri"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      }
    },
    "/v1/limits/request": {
      "post": {
        "operationId": "requestLimit",
        "summary": "Ask kosa8 for a higher running-sandbox limit; kosa8 answers the owner by email. Once a day",
        "tags": [
          "Billing"
        ],
        "x-kosa8-scope": "admin",
        "description": "Needs the `admin` scope (or one that includes it).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "max_running": {
                    "type": "integer",
                    "description": "Above the current limit"
                  },
                  "reason": {
                    "type": "string",
                    "maxLength": 500,
                    "description": "What the sandboxes are for"
                  }
                },
                "required": [
                  "max_running"
                ]
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Asked",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "requested": {
                      "type": "object"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          }
        }
      }
    },
    "/v1/usage/insights": {
      "get": {
        "operationId": "getUsageInsights",
        "summary": "Daily spend, top sandboxes, credit left and projected month-end spend",
        "tags": [
          "Billing"
        ],
        "x-kosa8-scope": "sandboxes:read",
        "description": "Needs the `sandboxes:read` scope (or one that includes it).",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      }
    },
    "/v1/onboarding": {
      "get": {
        "operationId": "getOnboarding",
        "summary": "Get started progress for this org",
        "tags": [
          "Account"
        ],
        "x-kosa8-scope": "any",
        "description": "Any valid key.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      },
      "post": {
        "operationId": "updateOnboarding",
        "summary": "Skip, resume or finish a Get started step",
        "tags": [
          "Account"
        ],
        "x-kosa8-scope": "sandboxes:write",
        "description": "Needs the `sandboxes:write` scope (or one that includes it).",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "action": {
                    "type": "string"
                  },
                  "step": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      }
    },
    "/v1/events": {
      "post": {
        "operationId": "recordEvent",
        "summary": "Record an allowed product event (referral_link_copied, moment_shown, moment_clicked); rate-limited",
        "tags": [
          "Account"
        ],
        "x-kosa8-scope": "any",
        "description": "Any valid key.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "moment": {
                    "type": "string",
                    "description": "moment_shown and moment_clicked: the moment's id"
                  }
                },
                "required": [
                  "name"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      }
    },
    "/v1/recommendations": {
      "get": {
        "operationId": "getRecommendations",
        "summary": "Up to two upgrade moments for this org, most urgent first, each grounded in the org's own usage and the real price tables",
        "tags": [
          "Billing"
        ],
        "x-kosa8-scope": "sandboxes:read",
        "description": "Needs the `sandboxes:read` scope (or one that includes it).",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "moments": {
                      "type": "array",
                      "maxItems": 2,
                      "items": {
                        "$ref": "#/components/schemas/Moment"
                      }
                    },
                    "suppressed": {
                      "type": "string",
                      "description": "checkout_in_progress: a checkout was opened in the last 30 minutes, so nothing is offered"
                    },
                    "milestones": {
                      "type": "object",
                      "properties": {
                        "first_sandbox_at": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "first_function_at": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        }
                      }
                    },
                    "generated_at": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      }
    },
    "/v1/recommendations/{id}/dismiss": {
      "post": {
        "operationId": "dismissRecommendation",
        "summary": "Hide a moment for this org for 14 days",
        "tags": [
          "Billing"
        ],
        "x-kosa8-scope": "sandboxes:read",
        "description": "Needs the `sandboxes:read` scope (or one that includes it).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The moment's id, e.g. add_card"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      }
    },
    "/v1/billing/checkout": {
      "post": {
        "operationId": "startCheckout",
        "summary": "Start checkout to add a payment method or plan",
        "tags": [
          "Billing"
        ],
        "x-kosa8-scope": "admin",
        "x-kosa8-role": "owner",
        "description": "Needs the `admin` scope (or one that includes it). Owner only: an owner member or the organization's own admin key; an admin member gets 403.",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "plan": {
                    "type": "string"
                  },
                  "yearly": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      }
    },
    "/v1/billing/portal": {
      "post": {
        "operationId": "openPortal",
        "summary": "Open the billing portal (invoices, payment method)",
        "tags": [
          "Billing"
        ],
        "x-kosa8-scope": "admin",
        "x-kosa8-role": "owner",
        "description": "Needs the `admin` scope (or one that includes it). Owner only: an owner member or the organization's own admin key; an admin member gets 403.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      }
    },
    "/v1/billing/sync": {
      "post": {
        "operationId": "syncBilling",
        "summary": "Re-check the payment provider for this org's subscription",
        "tags": [
          "Billing"
        ],
        "x-kosa8-scope": "admin",
        "x-kosa8-role": "owner",
        "description": "Needs the `admin` scope (or one that includes it). Owner only: an owner member or the organization's own admin key; an admin member gets 403.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          }
        }
      }
    },
    "/v1/billing/plan": {
      "post": {
        "operationId": "changePlan",
        "summary": "Change plan (Solo, Pro, Team, Scale; seats for Team and Scale, yearly or monthly); the prorated difference is charged now",
        "tags": [
          "Billing"
        ],
        "x-kosa8-scope": "admin",
        "x-kosa8-role": "owner",
        "description": "Needs the `admin` scope (or one that includes it). Owner only: an owner member or the organization's own admin key; an admin member gets 403.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          }
        }
      }
    },
    "/v1/billing/addons": {
      "get": {
        "operationId": "listAddons",
        "summary": "Add-on packs: each pack, its price, the limit it adds to and how many are in force. available is false when none is sold here",
        "tags": [
          "Billing"
        ],
        "x-kosa8-scope": "sandboxes:read",
        "description": "Needs the `sandboxes:read` scope (or one that includes it).",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      },
      "post": {
        "operationId": "addAddon",
        "summary": "Buy add-on packs ({addon: hours_100 | running_10, quantity}): monthly, stackable on any plan. Answers {url} for a checkout (the first of a kind) or {quantity} when added to the pack subscription. Needs a plan (402 plan_required)",
        "tags": [
          "Billing"
        ],
        "x-kosa8-scope": "admin",
        "x-kosa8-role": "owner",
        "description": "Needs the `admin` scope (or one that includes it). Owner only: an owner member or the organization's own admin key; an admin member gets 403.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "addon": {
                    "type": "string",
                    "enum": [
                      "hours_100",
                      "running_10"
                    ]
                  },
                  "quantity": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 100
                  }
                },
                "required": [
                  "addon"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          }
        }
      }
    },
    "/v1/billing/addons/{addon}": {
      "delete": {
        "operationId": "removeAddon",
        "summary": "Remove add-on packs (?quantity, default 1); the last one stops at the end of the month paid for (ends_at)",
        "tags": [
          "Billing"
        ],
        "x-kosa8-scope": "admin",
        "x-kosa8-role": "owner",
        "description": "Needs the `admin` scope (or one that includes it). Owner only: an owner member or the organization's own admin key; an admin member gets 403.",
        "parameters": [
          {
            "name": "addon",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "hours_100 or running_10"
          },
          {
            "name": "quantity",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            },
            "description": "how many packs to remove (default 1)"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          }
        }
      }
    },
    "/v1/billing/charge-now": {
      "post": {
        "operationId": "chargeNow",
        "summary": "Pay what is owed now (after a declined charge, once the card is fixed)",
        "tags": [
          "Billing"
        ],
        "x-kosa8-scope": "admin",
        "x-kosa8-role": "owner",
        "description": "Needs the `admin` scope (or one that includes it). Owner only: an owner member or the organization's own admin key; an admin member gets 403.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          }
        }
      }
    },
    "/v1/billing/licence": {
      "post": {
        "operationId": "linkLicence",
        "summary": "Link a kosa8 licence to the org",
        "tags": [
          "Billing"
        ],
        "x-kosa8-scope": "admin",
        "x-kosa8-role": "owner",
        "description": "Needs the `admin` scope (or one that includes it). Owner only: an owner member or the organization's own admin key; an admin member gets 403.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      }
    },
    "/v1/billing/machine-licence": {
      "post": {
        "operationId": "machineLicence",
        "summary": "The plan's licence keys, for kosa8 login to activate on a member's own machine (a person only)",
        "tags": [
          "Billing"
        ],
        "x-kosa8-scope": "sandboxes:write",
        "description": "Needs the `sandboxes:write` scope (or one that includes it).",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          }
        }
      }
    },
    "/v1/billing/credits": {
      "get": {
        "operationId": "getCredits",
        "summary": "Prepaid credit balance and packs",
        "tags": [
          "Billing"
        ],
        "x-kosa8-scope": "sandboxes:read",
        "description": "Needs the `sandboxes:read` scope (or one that includes it).",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      }
    },
    "/v1/referral": {
      "get": {
        "operationId": "getReferral",
        "summary": "Refer and earn link and invitations",
        "tags": [
          "Billing"
        ],
        "x-kosa8-scope": "sandboxes:read",
        "description": "Needs the `sandboxes:read` scope (or one that includes it).",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      }
    },
    "/v1/affiliate": {
      "get": {
        "operationId": "getAffiliate",
        "summary": "Affiliate program status",
        "tags": [
          "Billing"
        ],
        "x-kosa8-scope": "sandboxes:read",
        "description": "Needs the `sandboxes:read` scope (or one that includes it).",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      }
    },
    "/v1/affiliate/apply": {
      "post": {
        "operationId": "applyAffiliate",
        "summary": "Apply to the affiliate program",
        "tags": [
          "Billing"
        ],
        "x-kosa8-scope": "admin",
        "description": "Needs the `admin` scope (or one that includes it).",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          }
        }
      }
    },
    "/v1/affiliate/payout": {
      "post": {
        "operationId": "setAffiliatePayout",
        "summary": "Set affiliate payout details (method, email, country, legal name)",
        "tags": [
          "Billing"
        ],
        "x-kosa8-scope": "admin",
        "description": "Needs the `admin` scope (or one that includes it).",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          }
        }
      }
    },
    "/v1/byoc/tokens": {
      "get": {
        "operationId": "listHostTokens",
        "summary": "List host registration tokens",
        "tags": [
          "Own hosts"
        ],
        "x-kosa8-scope": "admin",
        "description": "Needs the `admin` scope (or one that includes it).",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      },
      "post": {
        "operationId": "createHostToken",
        "summary": "Create a host registration token (k8r_…, shown once)",
        "tags": [
          "Own hosts"
        ],
        "x-kosa8-scope": "admin",
        "description": "Needs the `admin` scope (or one that includes it).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "ttl_s": {
                    "type": "integer",
                    "minimum": 60,
                    "maximum": 2592000
                  }
                },
                "required": [
                  "name"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          }
        }
      }
    },
    "/v1/byoc/tokens/{id}": {
      "delete": {
        "operationId": "revokeHostToken",
        "summary": "Revoke a host registration token",
        "tags": [
          "Own hosts"
        ],
        "x-kosa8-scope": "admin",
        "description": "Needs the `admin` scope (or one that includes it).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Id"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      }
    },
    "/v1/byoc/hosts": {
      "get": {
        "operationId": "listOwnHosts",
        "summary": "The org's own hosts",
        "tags": [
          "Own hosts"
        ],
        "x-kosa8-scope": "sandboxes:read",
        "description": "Needs the `sandboxes:read` scope (or one that includes it).",
        "parameters": [
          {
            "name": "all",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ]
            },
            "description": "1 includes removed hosts"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      }
    },
    "/v1/byoc/hosts/{id}": {
      "delete": {
        "operationId": "removeOwnHost",
        "summary": "Remove an own host",
        "tags": [
          "Own hosts"
        ],
        "x-kosa8-scope": "admin",
        "description": "Needs the `admin` scope (or one that includes it).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Id"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      }
    },
    "/v1/functions": {
      "get": {
        "operationId": "listFunctions",
        "summary": "List functions",
        "tags": [
          "Functions"
        ],
        "x-kosa8-scope": "functions:invoke",
        "description": "Needs the `functions:invoke` scope (or one that includes it).",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      }
    },
    "/v1/functions/{name}": {
      "put": {
        "operationId": "deployFunction",
        "summary": "Deploy or replace a function (bumps version)",
        "tags": [
          "Functions"
        ],
        "x-kosa8-scope": "functions:deploy",
        "description": "Needs the `functions:deploy` scope (or one that includes it). 201 when the name is new (version 1); 200 when it replaces a deployed function.",
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Function name"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "runtime": {
                    "type": "string",
                    "enum": [
                      "python3.12",
                      "node22"
                    ]
                  },
                  "code": {
                    "type": "string",
                    "description": "The source, at most 1 MiB"
                  },
                  "env": {
                    "type": "object",
                    "maxProperties": 64,
                    "additionalProperties": {
                      "type": "string",
                      "maxLength": 4096
                    },
                    "description": "Names not starting with K8_; 16 KiB in all"
                  },
                  "timeout_s": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 90,
                    "default": 30
                  },
                  "web": {
                    "type": "string",
                    "enum": [
                      "off",
                      "public",
                      "key"
                    ],
                    "default": "off"
                  },
                  "schedule": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "A five-field cron expression (UTC), or null for none"
                  }
                },
                "required": [
                  "runtime",
                  "code"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "201": {
            "description": "Created: the first version",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "413": {
            "$ref": "#/components/responses/E413"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          }
        }
      },
      "get": {
        "operationId": "getFunction",
        "summary": "Get a function with its code",
        "tags": [
          "Functions"
        ],
        "x-kosa8-scope": "functions:deploy",
        "description": "Needs the `functions:deploy` scope (or one that includes it).",
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Function name"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      },
      "delete": {
        "operationId": "deleteFunction",
        "summary": "Delete a function",
        "tags": [
          "Functions"
        ],
        "x-kosa8-scope": "functions:deploy",
        "description": "Needs the `functions:deploy` scope (or one that includes it).",
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Function name"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      }
    },
    "/v1/functions/{name}/invoke": {
      "post": {
        "operationId": "invokeFunction",
        "summary": "Call a function: {event} → result, logs, timings",
        "tags": [
          "Functions"
        ],
        "x-kosa8-scope": "functions:invoke",
        "description": "Needs the `functions:invoke` scope (or one that includes it).",
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Function name"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "event": {}
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "402": {
            "$ref": "#/components/responses/E402"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          }
        }
      }
    },
    "/v1/functions/{name}/map": {
      "post": {
        "operationId": "mapFunction",
        "summary": "Call a function on up to 100 events",
        "tags": [
          "Functions"
        ],
        "x-kosa8-scope": "functions:invoke",
        "description": "Needs the `functions:invoke` scope (or one that includes it).",
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Function name"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "events": {
                    "type": "array",
                    "maxItems": 100
                  },
                  "concurrency": {
                    "type": "integer",
                    "maximum": 16
                  }
                },
                "required": [
                  "events"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "402": {
            "$ref": "#/components/responses/E402"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          }
        }
      }
    },
    "/v1/functions/{name}/invocations": {
      "get": {
        "operationId": "listInvocations",
        "summary": "Recent calls, newest first",
        "tags": [
          "Functions"
        ],
        "x-kosa8-scope": "functions:invoke",
        "description": "Needs the `functions:invoke` scope (or one that includes it).",
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Function name"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "How many"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      }
    },
    "/v1/members": {
      "get": {
        "operationId": "listMembers",
        "summary": "List members",
        "tags": [
          "Team"
        ],
        "x-kosa8-scope": "sandboxes:read",
        "description": "Needs the `sandboxes:read` scope (or one that includes it).",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      },
      "post": {
        "operationId": "putMember",
        "summary": "Invite or change a member",
        "tags": [
          "Team"
        ],
        "x-kosa8-scope": "admin",
        "description": "Needs the `admin` scope (or one that includes it).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email": {
                    "type": "string"
                  },
                  "role": {
                    "type": "string"
                  }
                },
                "required": [
                  "email",
                  "role"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      }
    },
    "/v1/members/{email}": {
      "delete": {
        "operationId": "deleteMember",
        "summary": "Remove a member",
        "tags": [
          "Team"
        ],
        "x-kosa8-scope": "admin",
        "description": "Needs the `admin` scope (or one that includes it).",
        "parameters": [
          {
            "name": "email",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Member email, percent-encoded"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      }
    },
    "/v1/sso": {
      "get": {
        "operationId": "getSSO",
        "summary": "The org's single sign-on connection (OIDC or SAML 2.0), what to enter in the IdP (saml_sp), and the SCIM base URL",
        "tags": [
          "Team"
        ],
        "x-kosa8-scope": "admin",
        "description": "Needs the `admin` scope (or one that includes it).",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      },
      "put": {
        "operationId": "putSSO",
        "summary": "Set up or change single sign-on: OIDC or SAML 2.0, domains, default role, just-in-time, enforcement, SCIM group-to-role mapping",
        "tags": [
          "Team"
        ],
        "x-kosa8-scope": "admin",
        "x-kosa8-role": "owner",
        "description": "Needs the `admin` scope (or one that includes it). Owner only: an owner member or the organization's own admin key; an admin member gets 403.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "protocol": {
                    "type": "string",
                    "enum": [
                      "oidc",
                      "saml"
                    ],
                    "description": "Default: the current protocol, else oidc"
                  },
                  "issuer": {
                    "type": "string",
                    "description": "OIDC: the provider's https issuer URL"
                  },
                  "client_id": {
                    "type": "string",
                    "description": "OIDC"
                  },
                  "client_secret": {
                    "type": "string",
                    "description": "OIDC; write only"
                  },
                  "idp_metadata_xml": {
                    "type": "string",
                    "description": "SAML: the IdP's metadata XML (entity ID, SSO URL and signing certificates are read from it)"
                  },
                  "idp_metadata_url": {
                    "type": "string",
                    "description": "SAML: an https URL to fetch the IdP's metadata from, once, now"
                  },
                  "idp_entity_id": {
                    "type": "string",
                    "description": "SAML: the IdP's entity ID (Issuer)"
                  },
                  "idp_sso_url": {
                    "type": "string",
                    "description": "SAML: the IdP's HTTP-Redirect single sign-on URL"
                  },
                  "idp_certificates": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "minItems": 1,
                    "maxItems": 2,
                    "description": "SAML: 1 or 2 PEM signing certificates (2 while rotating)"
                  },
                  "allow_idp_initiated": {
                    "type": "boolean",
                    "description": "SAML: an IdP app tile starts an ordinary SP-initiated sign-in. Default false"
                  },
                  "domains": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "default_role": {
                    "type": "string",
                    "enum": [
                      "admin",
                      "developer",
                      "viewer"
                    ]
                  },
                  "jit": {
                    "type": "boolean"
                  },
                  "enforce": {
                    "type": "boolean"
                  },
                  "scim_group_roles": {
                    "type": [
                      "object",
                      "null"
                    ],
                    "additionalProperties": {
                      "type": "string",
                      "enum": [
                        "admin",
                        "developer",
                        "viewer"
                      ]
                    },
                    "description": "SCIM group display name -> role"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      },
      "delete": {
        "operationId": "deleteSSO",
        "summary": "Remove single sign-on (and revoke the SCIM token)",
        "tags": [
          "Team"
        ],
        "x-kosa8-scope": "admin",
        "x-kosa8-role": "owner",
        "description": "Needs the `admin` scope (or one that includes it). Owner only: an owner member or the organization's own admin key; an admin member gets 403.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      }
    },
    "/v1/sso/domains/{domain}/verify": {
      "post": {
        "operationId": "verifySSODomain",
        "summary": "Check a domain's DNS TXT record",
        "tags": [
          "Team"
        ],
        "x-kosa8-scope": "admin",
        "x-kosa8-role": "owner",
        "description": "Needs the `admin` scope (or one that includes it). Owner only: an owner member or the organization's own admin key; an admin member gets 403.",
        "parameters": [
          {
            "name": "domain",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Domain"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      }
    },
    "/v1/sso/scim-token": {
      "get": {
        "operationId": "getScimToken",
        "summary": "The SCIM base URL and the live SCIM token's id and prefix (never its secret)",
        "tags": [
          "Team"
        ],
        "x-kosa8-scope": "admin",
        "x-kosa8-role": "owner",
        "description": "Needs the `admin` scope (or one that includes it). Owner only: an owner member or the organization's own admin key; an admin member gets 403.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      },
      "post": {
        "operationId": "createScimToken",
        "summary": "Make a SCIM bearer token (k8c_scim_…, shown once); any older token stops working at once",
        "tags": [
          "Team"
        ],
        "x-kosa8-scope": "admin",
        "x-kosa8-role": "owner",
        "description": "Needs the `admin` scope (or one that includes it). Owner only: an owner member or the organization's own admin key; an admin member gets 403.",
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          }
        }
      },
      "delete": {
        "operationId": "revokeScimToken",
        "summary": "Revoke the SCIM token",
        "tags": [
          "Team"
        ],
        "x-kosa8-scope": "admin",
        "x-kosa8-role": "owner",
        "description": "Needs the `admin` scope (or one that includes it). Owner only: an owner member or the organization's own admin key; an admin member gets 403.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      }
    },
    "/v1/audit": {
      "get": {
        "operationId": "listAudit",
        "summary": "Audit events, newest first",
        "tags": [
          "Audit"
        ],
        "x-kosa8-scope": "audit:read",
        "description": "Needs the `audit:read` scope (or one that includes it).",
        "parameters": [
          {
            "name": "sandbox_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "sandbox_id"
          },
          {
            "name": "actor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "actor"
          },
          {
            "name": "action",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "action"
          },
          {
            "name": "since",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "since"
          },
          {
            "name": "until",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "until"
          },
          {
            "name": "before_seq",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "before_seq"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "limit"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      }
    },
    "/v1/audit/verify": {
      "get": {
        "operationId": "verifyAudit",
        "summary": "Recompute the org's hash chain",
        "tags": [
          "Audit"
        ],
        "x-kosa8-scope": "audit:read",
        "description": "Needs the `audit:read` scope (or one that includes it).",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      }
    },
    "/v1/audit/export": {
      "get": {
        "operationId": "exportAudit",
        "summary": "Audit events as NDJSON, oldest first, with hashes",
        "tags": [
          "Audit"
        ],
        "x-kosa8-scope": "audit:read",
        "description": "Needs the `audit:read` scope (or one that includes it).",
        "responses": {
          "200": {
            "description": "NDJSON",
            "content": {
              "application/x-ndjson": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      }
    },
    "/v1/attack/scorecards": {
      "get": {
        "operationId": "listScorecards",
        "summary": "Agent attack scorecards uploaded by the org, newest first",
        "tags": [
          "Attack tests"
        ],
        "x-kosa8-scope": "sandboxes:read",
        "description": "Needs the `sandboxes:read` scope (or one that includes it).",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "At most 50; default 10"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      },
      "post": {
        "operationId": "uploadScorecard",
        "summary": "Upload a signed scorecard from `kosa8 attack run`; the signature is checked before it is stored",
        "tags": [
          "Attack tests"
        ],
        "x-kosa8-scope": "sandboxes:write",
        "description": "Needs the `sandboxes:write` scope (or one that includes it).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "signed": {
                    "type": "object",
                    "additionalProperties": true
                  }
                },
                "required": [
                  "signed"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "413": {
            "$ref": "#/components/responses/E413"
          },
          "422": {
            "$ref": "#/components/responses/E422"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          }
        }
      }
    },
    "/v1/attack/scorecards/{id}": {
      "get": {
        "operationId": "getScorecard",
        "summary": "One scorecard, with the signed file as uploaded",
        "tags": [
          "Attack tests"
        ],
        "x-kosa8-scope": "sandboxes:read",
        "description": "Needs the `sandboxes:read` scope (or one that includes it).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Id"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      }
    },
    "/v1/webhooks": {
      "get": {
        "operationId": "listWebhooks",
        "summary": "List webhook endpoints",
        "tags": [
          "Webhooks"
        ],
        "x-kosa8-scope": "admin",
        "description": "Needs the `admin` scope (or one that includes it).",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "webhooks": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Webhook"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      },
      "post": {
        "operationId": "createWebhook",
        "summary": "Add an endpoint; the whsec_ signing secret is shown once",
        "tags": [
          "Webhooks"
        ],
        "x-kosa8-scope": "admin",
        "description": "Needs the `admin` scope (or one that includes it).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri"
                  },
                  "events": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "sandbox.created",
                        "sandbox.deleted",
                        "sandbox.slept",
                        "sandbox.woke",
                        "sandbox.error",
                        "sandbox.killed",
                        "sandbox.oom",
                        "function.deployed",
                        "function.invocation.failed",
                        "spending_cap.reached",
                        "plan.purchased",
                        "plan.changed",
                        "plan.canceled",
                        "plan.renewed",
                        "plan.payment_failed",
                        "seats.changed",
                        "plan_required.blocked",
                        "plan_limit.near",
                        "plan_limit.reached",
                        "plan_feature.blocked",
                        "hours.reset",
                        "capacity.unavailable",
                        "legacy_access.ending",
                        "legacy_access.ended",
                        "addon.purchased",
                        "addon.canceled",
                        "agent.tool_call.blocked",
                        "agent.tool_call.decided"
                      ]
                    }
                  },
                  "description": {
                    "type": "string"
                  }
                },
                "required": [
                  "url"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "webhook": {
                      "$ref": "#/components/schemas/Webhook"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      }
    },
    "/v1/agent-hooks/events": {
      "post": {
        "operationId": "agentHookEvent",
        "summary": "Record an agent hook decision or session event from a developer's machine (kosa8 hooks install --cloud)",
        "tags": [
          "Webhooks"
        ],
        "x-kosa8-scope": "sandboxes:write",
        "description": "Needs the `sandboxes:write` scope (or one that includes it). The decision was made by kosa8's rules on the machine; the answer may only be stricter (a frozen organization refuses every call). agent.tool_call.blocked (deny or ask) and agent.tool_call.decided are recorded in the audit log and sent to webhooks that subscribe to them.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "event": {
                    "type": "object",
                    "properties": {
                      "action": {
                        "type": "string",
                        "enum": [
                          "agent.tool_call.decided",
                          "agent.tool_call.blocked",
                          "agent.session.started",
                          "agent.session.stopped",
                          "agent.session.ended",
                          "agent.file.edited"
                        ]
                      },
                      "harness": {
                        "type": "string",
                        "enum": [
                          "claude-code",
                          "cursor"
                        ]
                      },
                      "event": {
                        "type": "string"
                      },
                      "tool": {
                        "type": "string"
                      },
                      "effect": {
                        "type": "string",
                        "enum": [
                          "allow",
                          "flag",
                          "ask",
                          "deny"
                        ]
                      },
                      "reason": {
                        "type": "string"
                      },
                      "rules": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      "subject": {
                        "type": "string",
                        "description": "the command or path, clipped to 300 characters; never a file's contents"
                      },
                      "args_sha256": {
                        "type": "string"
                      },
                      "session": {
                        "type": "string"
                      },
                      "cwd": {
                        "type": "string"
                      },
                      "mode": {
                        "type": "string",
                        "enum": [
                          "check",
                          "sandbox"
                        ]
                      },
                      "sandboxed": {
                        "type": "boolean"
                      }
                    },
                    "required": [
                      "action",
                      "harness"
                    ]
                  }
                },
                "required": [
                  "event"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "action": {
                      "type": "string"
                    },
                    "effect": {
                      "type": "string",
                      "enum": [
                        "allow",
                        "flag",
                        "ask",
                        "deny"
                      ]
                    },
                    "reason": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      }
    },
    "/v1/integrations/github": {
      "get": {
        "operationId": "githubStatus",
        "summary": "GitHub Actions runners: linked installations and the link to install the kosa8 GitHub App",
        "tags": [
          "Integrations"
        ],
        "x-kosa8-scope": "admin",
        "description": "Needs the `admin` scope (or one that includes it). Jobs whose runs-on includes the kosa8 label then run on an ephemeral self-hosted runner in a persistent sandbox of this org; a kosa8-4x8 (2x4, 8x16, 16x32) label picks the size.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "configured": {
                      "type": "boolean"
                    },
                    "installations": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      }
                    },
                    "install_url": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      }
    },
    "/v1/integrations/github/{installation_id}": {
      "delete": {
        "operationId": "githubUnlink",
        "summary": "Stop taking this installation's jobs",
        "tags": [
          "Integrations"
        ],
        "x-kosa8-scope": "admin",
        "description": "Needs the `admin` scope (or one that includes it).",
        "parameters": [
          {
            "name": "installation_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          }
        }
      }
    },
    "/v1/webhooks/{id}": {
      "delete": {
        "operationId": "deleteWebhook",
        "summary": "Stop sending, including retries",
        "tags": [
          "Webhooks"
        ],
        "x-kosa8-scope": "admin",
        "description": "Needs the `admin` scope (or one that includes it).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Id"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      }
    },
    "/v1/webhooks/{id}/deliveries": {
      "get": {
        "operationId": "listWebhookDeliveries",
        "summary": "Recent deliveries",
        "tags": [
          "Webhooks"
        ],
        "x-kosa8-scope": "admin",
        "description": "Needs the `admin` scope (or one that includes it).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Id"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "How many"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      }
    },
    "/v1/store/items": {
      "get": {
        "operationId": "listStoreItems",
        "summary": "Published kosa8 Store items (public)",
        "tags": [
          "Store"
        ],
        "security": [],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Search text"
          },
          {
            "name": "category",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Category"
          },
          {
            "name": "kind",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Kind"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      }
                    },
                    "categories": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createStoreItem",
        "summary": "Create a Store listing (picks the org's creator handle the first time)",
        "tags": [
          "Store"
        ],
        "x-kosa8-scope": "admin",
        "description": "Needs the `admin` scope (or one that includes it).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "creator": {
                    "type": "string"
                  },
                  "name": {
                    "type": "string"
                  },
                  "kind": {
                    "type": "string",
                    "enum": [
                      "template",
                      "save_state",
                      "environment",
                      "mcp_server",
                      "function"
                    ]
                  },
                  "title": {
                    "type": "string"
                  },
                  "summary": {
                    "type": "string"
                  },
                  "category": {
                    "type": "string"
                  }
                },
                "required": [
                  "name",
                  "kind",
                  "title",
                  "summary",
                  "category"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "item": {
                      "type": "object",
                      "additionalProperties": true
                    },
                    "disclosure": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          }
        }
      }
    },
    "/v1/store/items/{creator}/{name}": {
      "get": {
        "operationId": "getStoreItem",
        "summary": "One published Store item, with README and review checks (public)",
        "tags": [
          "Store"
        ],
        "security": [],
        "parameters": [
          {
            "name": "creator",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Store creator handle"
          },
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Store item name"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      }
    },
    "/v1/store/terms": {
      "get": {
        "operationId": "getStoreTerms",
        "summary": "Store Guidelines, creator agreement, fee and kickback rates (public)",
        "tags": [
          "Store"
        ],
        "security": [],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          }
        }
      }
    },
    "/v1/store/mine": {
      "get": {
        "operationId": "myStoreItems",
        "summary": "This org's Store listings, versions and posts",
        "tags": [
          "Store"
        ],
        "x-kosa8-scope": "sandboxes:read",
        "description": "Needs the `sandboxes:read` scope (or one that includes it).",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      }
    },
    "/v1/store/items/{creator}/{name}/versions": {
      "post": {
        "operationId": "createStoreVersion",
        "summary": "Add a draft version",
        "tags": [
          "Store"
        ],
        "x-kosa8-scope": "admin",
        "description": "Needs the `admin` scope (or one that includes it).",
        "parameters": [
          {
            "name": "creator",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Store creator handle"
          },
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Store item name"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "version": {
                    "type": "string",
                    "description": "MAJOR.MINOR.PATCH; immutable once submitted"
                  },
                  "source": {
                    "type": "object",
                    "properties": {
                      "template": {
                        "type": "string",
                        "description": "A kosa8 Cloud template key"
                      },
                      "image": {
                        "type": "string"
                      },
                      "checkpoint": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "template"
                    ]
                  },
                  "egress": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Every host the item contacts (or *.domain)"
                  },
                  "env_names": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Environment variable NAMES it reads; never values"
                  },
                  "smoke_test": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "A command that must exit 0"
                  },
                  "tools": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string"
                        },
                        "description": {
                          "type": "string"
                        }
                      }
                    },
                    "description": "mcp_server only: pinned tool descriptions"
                  },
                  "readme": {
                    "type": "string"
                  },
                  "changelog": {
                    "type": "string"
                  },
                  "price_model": {
                    "type": "string",
                    "enum": [
                      "free",
                      "per_run",
                      "per_hour",
                      "monthly"
                    ]
                  },
                  "price_usd": {
                    "type": "number"
                  }
                },
                "required": [
                  "version",
                  "source",
                  "smoke_test"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "version": {
                      "type": "object",
                      "additionalProperties": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          }
        }
      }
    },
    "/v1/store/items/{creator}/{name}/versions/{version}": {
      "get": {
        "operationId": "getStoreVersion",
        "summary": "A version of your item, with its checks and reviewer notes",
        "tags": [
          "Store"
        ],
        "x-kosa8-scope": "sandboxes:read",
        "description": "Needs the `sandboxes:read` scope (or one that includes it).",
        "parameters": [
          {
            "name": "creator",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Store creator handle"
          },
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Store item name"
          },
          {
            "name": "version",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Version, MAJOR.MINOR.PATCH"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      },
      "patch": {
        "operationId": "updateStoreVersion",
        "summary": "Change a draft version",
        "tags": [
          "Store"
        ],
        "x-kosa8-scope": "admin",
        "description": "Needs the `admin` scope (or one that includes it).",
        "parameters": [
          {
            "name": "creator",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Store creator handle"
          },
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Store item name"
          },
          {
            "name": "version",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Version, MAJOR.MINOR.PATCH"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          }
        }
      }
    },
    "/v1/store/items/{creator}/{name}/versions/{version}/submit": {
      "post": {
        "operationId": "submitStoreVersion",
        "summary": "Submit for review: needs two posts on two platforms and accept_agreement",
        "tags": [
          "Store"
        ],
        "x-kosa8-scope": "admin",
        "description": "Needs the `admin` scope (or one that includes it).",
        "parameters": [
          {
            "name": "creator",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Store creator handle"
          },
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Store item name"
          },
          {
            "name": "version",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Version, MAJOR.MINOR.PATCH"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "accept_agreement": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "accept_agreement"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          }
        }
      }
    },
    "/v1/store/items/{creator}/{name}/versions/{version}/publish": {
      "post": {
        "operationId": "publishStoreVersion",
        "summary": "Publish an approved version",
        "tags": [
          "Store"
        ],
        "x-kosa8-scope": "admin",
        "description": "Needs the `admin` scope (or one that includes it).",
        "parameters": [
          {
            "name": "creator",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Store creator handle"
          },
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Store item name"
          },
          {
            "name": "version",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Version, MAJOR.MINOR.PATCH"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          }
        }
      }
    },
    "/v1/store/items/{creator}/{name}/versions/{version}/appeal": {
      "post": {
        "operationId": "appealStoreVersion",
        "summary": "Appeal a rejection, once",
        "tags": [
          "Store"
        ],
        "x-kosa8-scope": "admin",
        "description": "Needs the `admin` scope (or one that includes it).",
        "parameters": [
          {
            "name": "creator",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Store creator handle"
          },
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Store item name"
          },
          {
            "name": "version",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Version, MAJOR.MINOR.PATCH"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "note": {
                    "type": "string"
                  }
                },
                "required": [
                  "note"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          }
        }
      }
    },
    "/v1/store/items/{creator}/{name}/proofs": {
      "post": {
        "operationId": "addStoreProof",
        "summary": "Add a public post about the item (X, LinkedIn, YouTube, Reddit, Hacker News, dev.to/Hashnode/Medium, GitHub)",
        "tags": [
          "Store"
        ],
        "x-kosa8-scope": "admin",
        "description": "Needs the `admin` scope (or one that includes it).",
        "parameters": [
          {
            "name": "creator",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Store creator handle"
          },
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Store item name"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri"
                  }
                },
                "required": [
                  "url"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "proof": {
                      "type": "object",
                      "additionalProperties": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          }
        }
      }
    },
    "/v1/store/items/{creator}/{name}/proofs/{id}": {
      "delete": {
        "operationId": "deleteStoreProof",
        "summary": "Remove an unverified post",
        "tags": [
          "Store"
        ],
        "x-kosa8-scope": "admin",
        "description": "Needs the `admin` scope (or one that includes it).",
        "parameters": [
          {
            "name": "creator",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Store creator handle"
          },
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Store item name"
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Id"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          }
        }
      }
    },
    "/v1/store/items/{creator}/{name}/rating": {
      "put": {
        "operationId": "rateStoreItem",
        "summary": "Rate 1–5 stars; only orgs that ran the item",
        "tags": [
          "Store"
        ],
        "x-kosa8-scope": "sandboxes:write",
        "description": "Needs the `sandboxes:write` scope (or one that includes it).",
        "parameters": [
          {
            "name": "creator",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Store creator handle"
          },
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Store item name"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "stars": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 5
                  }
                },
                "required": [
                  "stars"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          }
        }
      }
    },
    "/v1/store/earnings": {
      "get": {
        "operationId": "getStoreEarnings",
        "summary": "Creator earnings: royalties owed (held, available, paid) and kickback credit",
        "tags": [
          "Store"
        ],
        "x-kosa8-scope": "sandboxes:read",
        "description": "Needs the `sandboxes:read` scope (or one that includes it).",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      }
    },
    "/v1/store/payout-profile": {
      "put": {
        "operationId": "putStorePayoutProfile",
        "summary": "Where payouts go (PayPal or Wise). Never send a tax id",
        "tags": [
          "Store"
        ],
        "x-kosa8-scope": "admin",
        "description": "Needs the `admin` scope (or one that includes it).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "method": {
                    "type": "string",
                    "enum": [
                      "paypal",
                      "wise"
                    ]
                  },
                  "payout_email": {
                    "type": "string"
                  },
                  "country": {
                    "type": "string"
                  },
                  "legal_name": {
                    "type": "string"
                  }
                },
                "required": [
                  "method",
                  "payout_email",
                  "country",
                  "legal_name"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          }
        }
      }
    },
    "/v1/security/posture": {
      "get": {
        "operationId": "getSecurityPosture",
        "summary": "The org's security checklist from its own settings, with passed/total",
        "tags": [
          "Security"
        ],
        "x-kosa8-scope": "audit:read",
        "description": "Needs the `audit:read` scope (or one that includes it).",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      }
    },
    "/v1/security/inventory": {
      "get": {
        "operationId": "getAgentInventory",
        "summary": "Every API key and member, with the sandboxes and functions each made",
        "tags": [
          "Security"
        ],
        "x-kosa8-scope": "audit:read",
        "description": "Needs the `audit:read` scope (or one that includes it).",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      }
    },
    "/v1/security/evidence": {
      "get": {
        "operationId": "getEvidence",
        "summary": "A JSON bundle of the posture and audit events in a range, with its SHA-256",
        "tags": [
          "Security"
        ],
        "x-kosa8-scope": "audit:read",
        "description": "Needs the `audit:read` scope (or one that includes it).",
        "parameters": [
          {
            "name": "since",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "since"
          },
          {
            "name": "until",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "until"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      }
    },
    "/v1/security/freeze": {
      "get": {
        "operationId": "getFreeze",
        "summary": "Whether the org is frozen",
        "tags": [
          "Security"
        ],
        "x-kosa8-scope": "any",
        "description": "Any valid key.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      },
      "post": {
        "operationId": "freezeOrg",
        "summary": "Freeze the org: refuse new work, sleep running sandboxes, optionally suspend keys",
        "tags": [
          "Security"
        ],
        "x-kosa8-scope": "admin",
        "description": "Needs the `admin` scope (or one that includes it).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "confirm": {
                    "type": "string",
                    "description": "The organization's name, typed"
                  },
                  "reason": {
                    "type": "string"
                  },
                  "suspend_keys": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "confirm"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          }
        }
      }
    },
    "/v1/security/unfreeze": {
      "post": {
        "operationId": "unfreezeOrg",
        "summary": "Unfreeze the org; suspended keys are restored unless restore_keys is false",
        "tags": [
          "Security"
        ],
        "x-kosa8-scope": "admin",
        "description": "Needs the `admin` scope (or one that includes it).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "confirm": {
                    "type": "string"
                  },
                  "restore_keys": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "confirm"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          }
        }
      }
    },
    "/v1/security/siem": {
      "get": {
        "operationId": "listSiemDestinations",
        "summary": "Where the audit log streams",
        "tags": [
          "Security"
        ],
        "x-kosa8-scope": "admin",
        "description": "Needs the `admin` scope (or one that includes it).",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      },
      "post": {
        "operationId": "createSiemDestination",
        "summary": "Stream the audit log as OCSF API Activity to a webhook, Splunk HEC or Datadog",
        "tags": [
          "Security"
        ],
        "x-kosa8-scope": "admin",
        "description": "Needs the `admin` scope (or one that includes it).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "kind": {
                    "type": "string",
                    "enum": [
                      "webhook",
                      "splunk_hec",
                      "datadog"
                    ]
                  },
                  "name": {
                    "type": "string"
                  },
                  "url": {
                    "type": "string",
                    "format": "uri"
                  },
                  "token": {
                    "type": "string"
                  },
                  "api_key": {
                    "type": "string"
                  },
                  "site": {
                    "type": "string"
                  },
                  "index": {
                    "type": "string"
                  },
                  "sourcetype": {
                    "type": "string"
                  },
                  "start": {
                    "type": "string",
                    "enum": [
                      "beginning",
                      "now"
                    ]
                  }
                },
                "required": [
                  "kind"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          }
        }
      }
    },
    "/v1/security/siem/{id}": {
      "delete": {
        "operationId": "deleteSiemDestination",
        "summary": "Stop streaming to a destination",
        "tags": [
          "Security"
        ],
        "x-kosa8-scope": "admin",
        "description": "Needs the `admin` scope (or one that includes it).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Id"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      }
    },
    "/v1/security/siem/{id}/test": {
      "post": {
        "operationId": "testSiemDestination",
        "summary": "Send one test event now",
        "tags": [
          "Security"
        ],
        "x-kosa8-scope": "admin",
        "description": "Needs the `admin` scope (or one that includes it).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Id"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      }
    },
    "/v1/webhooks/{id}/test": {
      "post": {
        "operationId": "testWebhook",
        "summary": "Send a webhook.test event now",
        "tags": [
          "Webhooks"
        ],
        "x-kosa8-scope": "admin",
        "description": "Needs the `admin` scope (or one that includes it).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Id"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      }
    },
    "/v1/pipelines/runs": {
      "get": {
        "operationId": "listPipelineRuns",
        "summary": "Pipeline runs, newest first",
        "tags": [
          "Pipelines"
        ],
        "x-kosa8-scope": "sandboxes:read",
        "description": "Needs the `sandboxes:read` scope (or one that includes it).",
        "parameters": [
          {
            "name": "state",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "runs": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "repo_url": {
                            "type": "string"
                          },
                          "ref": {
                            "type": "string"
                          },
                          "sha": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "branch": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "event": {
                            "type": "string"
                          },
                          "workflow": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "job": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "mode": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "enum": [
                              "native",
                              "act",
                              null
                            ],
                            "description": "native: .kosa8/pipeline.yml; act: .github/workflows through act"
                          },
                          "state": {
                            "type": "string",
                            "enum": [
                              "queued",
                              "running",
                              "success",
                              "failure",
                              "cancelled",
                              "error",
                              "skipped"
                            ]
                          },
                          "error": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "warnings": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "size": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "secrets": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "hook_id": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "timeout_s": {
                            "type": "integer"
                          },
                          "created_at": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "started_at": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "format": "date-time"
                          },
                          "finished_at": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "format": "date-time"
                          },
                          "duration_ms": {
                            "type": [
                              "integer",
                              "null"
                            ]
                          },
                          "jobs": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "name": {
                                  "type": "string",
                                  "description": "The job's name; for act runs, the workflow job id, and _act for the sandbox that ran act"
                                },
                                "kind": {
                                  "type": "string",
                                  "enum": [
                                    "native",
                                    "driver",
                                    "act"
                                  ]
                                },
                                "state": {
                                  "type": "string",
                                  "enum": [
                                    "pending",
                                    "booting",
                                    "running",
                                    "success",
                                    "failure",
                                    "cancelled",
                                    "skipped",
                                    "error"
                                  ]
                                },
                                "size": {
                                  "type": [
                                    "string",
                                    "null"
                                  ]
                                },
                                "needs": {
                                  "type": "array",
                                  "items": {
                                    "type": "string"
                                  }
                                },
                                "sandbox_id": {
                                  "type": [
                                    "string",
                                    "null"
                                  ]
                                },
                                "exit": {
                                  "type": [
                                    "integer",
                                    "null"
                                  ]
                                },
                                "error": {
                                  "type": [
                                    "string",
                                    "null"
                                  ]
                                },
                                "steps": {
                                  "description": "Native jobs: each step's name, state, exit and ms"
                                },
                                "log_bytes": {
                                  "type": "integer"
                                },
                                "log_truncated": {
                                  "type": "boolean"
                                },
                                "started_at": {
                                  "type": [
                                    "string",
                                    "null"
                                  ],
                                  "format": "date-time"
                                },
                                "finished_at": {
                                  "type": [
                                    "string",
                                    "null"
                                  ],
                                  "format": "date-time"
                                },
                                "duration_ms": {
                                  "type": [
                                    "integer",
                                    "null"
                                  ]
                                }
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      },
      "post": {
        "operationId": "createPipelineRun",
        "summary": "Run a repository's .kosa8/pipeline.yml, or its .github/workflows through act",
        "tags": [
          "Pipelines"
        ],
        "x-kosa8-scope": "sandboxes:write",
        "description": "Needs the `sandboxes:write` scope (or one that includes it). Each job runs in a sized sandbox made as this organization, billed and limited as any sandbox. See docs/guides/cloud-pipelines.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "repo_url": {
                    "type": "string",
                    "description": "https:// clone URL, no credentials, such as https://github.com/acme/app.git"
                  },
                  "ref": {
                    "type": "string",
                    "description": "Branch, tag, SHA or refs/… (default main)"
                  },
                  "event": {
                    "type": "string",
                    "enum": [
                      "push",
                      "pull_request",
                      "workflow_dispatch",
                      "schedule"
                    ],
                    "description": "Default workflow_dispatch"
                  },
                  "workflow": {
                    "type": "string",
                    "description": "act runs: one file in .github/workflows (default all)"
                  },
                  "job": {
                    "type": "string",
                    "description": "act runs: one job id"
                  },
                  "inputs": {
                    "type": "object",
                    "additionalProperties": {
                      "type": [
                        "string",
                        "number",
                        "boolean"
                      ]
                    },
                    "description": "workflow_dispatch inputs"
                  },
                  "size": {
                    "type": "string",
                    "description": "act runs: the sandbox size (default 4x8). Native runs size each job in the file"
                  },
                  "secrets": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "maxItems": 32,
                    "description": "kosa8 secret names (each made with pipelines: true); a job gets each as NAME_IN_CAPS"
                  },
                  "token_secret": {
                    "type": "string",
                    "description": "A secret holding a token that can read the repository (private repositories)"
                  },
                  "status_secret": {
                    "type": "string",
                    "description": "A secret holding a GitHub token with commit status write: the run sets kosa8/pipelines on the commit"
                  },
                  "timeout_s": {
                    "type": "integer",
                    "minimum": 60,
                    "maximum": 21600,
                    "description": "Default 3600"
                  }
                },
                "required": [
                  "repo_url"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "run": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "repo_url": {
                          "type": "string"
                        },
                        "ref": {
                          "type": "string"
                        },
                        "sha": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "branch": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "event": {
                          "type": "string"
                        },
                        "workflow": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "job": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "mode": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "enum": [
                            "native",
                            "act",
                            null
                          ],
                          "description": "native: .kosa8/pipeline.yml; act: .github/workflows through act"
                        },
                        "state": {
                          "type": "string",
                          "enum": [
                            "queued",
                            "running",
                            "success",
                            "failure",
                            "cancelled",
                            "error",
                            "skipped"
                          ]
                        },
                        "error": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "warnings": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "size": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "secrets": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "hook_id": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "timeout_s": {
                          "type": "integer"
                        },
                        "created_at": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "started_at": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "finished_at": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "duration_ms": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "jobs": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "name": {
                                "type": "string",
                                "description": "The job's name; for act runs, the workflow job id, and _act for the sandbox that ran act"
                              },
                              "kind": {
                                "type": "string",
                                "enum": [
                                  "native",
                                  "driver",
                                  "act"
                                ]
                              },
                              "state": {
                                "type": "string",
                                "enum": [
                                  "pending",
                                  "booting",
                                  "running",
                                  "success",
                                  "failure",
                                  "cancelled",
                                  "skipped",
                                  "error"
                                ]
                              },
                              "size": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "needs": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              },
                              "sandbox_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "exit": {
                                "type": [
                                  "integer",
                                  "null"
                                ]
                              },
                              "error": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "steps": {
                                "description": "Native jobs: each step's name, state, exit and ms"
                              },
                              "log_bytes": {
                                "type": "integer"
                              },
                              "log_truncated": {
                                "type": "boolean"
                              },
                              "started_at": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "format": "date-time"
                              },
                              "finished_at": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "format": "date-time"
                              },
                              "duration_ms": {
                                "type": [
                                  "integer",
                                  "null"
                                ]
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          }
        }
      }
    },
    "/v1/pipelines/runs/{id}": {
      "get": {
        "operationId": "getPipelineRun",
        "summary": "A run and its jobs (a live run's jobs are read first)",
        "tags": [
          "Pipelines"
        ],
        "x-kosa8-scope": "sandboxes:read",
        "description": "Needs the `sandboxes:read` scope (or one that includes it).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Pipeline run id (prun_…)"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "run": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "repo_url": {
                          "type": "string"
                        },
                        "ref": {
                          "type": "string"
                        },
                        "sha": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "branch": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "event": {
                          "type": "string"
                        },
                        "workflow": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "job": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "mode": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "enum": [
                            "native",
                            "act",
                            null
                          ],
                          "description": "native: .kosa8/pipeline.yml; act: .github/workflows through act"
                        },
                        "state": {
                          "type": "string",
                          "enum": [
                            "queued",
                            "running",
                            "success",
                            "failure",
                            "cancelled",
                            "error",
                            "skipped"
                          ]
                        },
                        "error": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "warnings": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "size": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "secrets": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "hook_id": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "timeout_s": {
                          "type": "integer"
                        },
                        "created_at": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "started_at": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "finished_at": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "duration_ms": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "jobs": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "name": {
                                "type": "string",
                                "description": "The job's name; for act runs, the workflow job id, and _act for the sandbox that ran act"
                              },
                              "kind": {
                                "type": "string",
                                "enum": [
                                  "native",
                                  "driver",
                                  "act"
                                ]
                              },
                              "state": {
                                "type": "string",
                                "enum": [
                                  "pending",
                                  "booting",
                                  "running",
                                  "success",
                                  "failure",
                                  "cancelled",
                                  "skipped",
                                  "error"
                                ]
                              },
                              "size": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "needs": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              },
                              "sandbox_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "exit": {
                                "type": [
                                  "integer",
                                  "null"
                                ]
                              },
                              "error": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "steps": {
                                "description": "Native jobs: each step's name, state, exit and ms"
                              },
                              "log_bytes": {
                                "type": "integer"
                              },
                              "log_truncated": {
                                "type": "boolean"
                              },
                              "started_at": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "format": "date-time"
                              },
                              "finished_at": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "format": "date-time"
                              },
                              "duration_ms": {
                                "type": [
                                  "integer",
                                  "null"
                                ]
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      }
    },
    "/v1/pipelines/runs/{id}/logs": {
      "get": {
        "operationId": "getPipelineLogs",
        "summary": "A run's logs by job, secrets replaced with ***",
        "tags": [
          "Pipelines"
        ],
        "x-kosa8-scope": "sandboxes:read",
        "description": "Needs the `sandboxes:read` scope (or one that includes it).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Pipeline run id (prun_…)"
          },
          {
            "name": "job",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "after",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "Only chunks after this one (next from the last call)"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "run_id": {
                      "type": "string"
                    },
                    "state": {
                      "type": "string"
                    },
                    "done": {
                      "type": "boolean"
                    },
                    "logs": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "job": {
                            "type": "string"
                          },
                          "state": {
                            "type": "string"
                          },
                          "text": {
                            "type": "string"
                          },
                          "next": {
                            "type": "integer"
                          },
                          "bytes": {
                            "type": "integer"
                          },
                          "truncated": {
                            "type": "boolean"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      }
    },
    "/v1/pipelines/runs/{id}/cancel": {
      "post": {
        "operationId": "cancelPipelineRun",
        "summary": "Cancel a run: its sandboxes are deleted",
        "tags": [
          "Pipelines"
        ],
        "x-kosa8-scope": "sandboxes:write",
        "description": "Needs the `sandboxes:write` scope (or one that includes it).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Pipeline run id (prun_…)"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "run": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "repo_url": {
                          "type": "string"
                        },
                        "ref": {
                          "type": "string"
                        },
                        "sha": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "branch": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "event": {
                          "type": "string"
                        },
                        "workflow": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "job": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "mode": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "enum": [
                            "native",
                            "act",
                            null
                          ],
                          "description": "native: .kosa8/pipeline.yml; act: .github/workflows through act"
                        },
                        "state": {
                          "type": "string",
                          "enum": [
                            "queued",
                            "running",
                            "success",
                            "failure",
                            "cancelled",
                            "error",
                            "skipped"
                          ]
                        },
                        "error": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "warnings": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "size": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "secrets": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "hook_id": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "timeout_s": {
                          "type": "integer"
                        },
                        "created_at": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "started_at": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "finished_at": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "duration_ms": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "jobs": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "name": {
                                "type": "string",
                                "description": "The job's name; for act runs, the workflow job id, and _act for the sandbox that ran act"
                              },
                              "kind": {
                                "type": "string",
                                "enum": [
                                  "native",
                                  "driver",
                                  "act"
                                ]
                              },
                              "state": {
                                "type": "string",
                                "enum": [
                                  "pending",
                                  "booting",
                                  "running",
                                  "success",
                                  "failure",
                                  "cancelled",
                                  "skipped",
                                  "error"
                                ]
                              },
                              "size": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "needs": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              },
                              "sandbox_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "exit": {
                                "type": [
                                  "integer",
                                  "null"
                                ]
                              },
                              "error": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "steps": {
                                "description": "Native jobs: each step's name, state, exit and ms"
                              },
                              "log_bytes": {
                                "type": "integer"
                              },
                              "log_truncated": {
                                "type": "boolean"
                              },
                              "started_at": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "format": "date-time"
                              },
                              "finished_at": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "format": "date-time"
                              },
                              "duration_ms": {
                                "type": [
                                  "integer",
                                  "null"
                                ]
                              }
                            }
                          }
                        }
                      }
                    },
                    "cancelled": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          }
        }
      }
    },
    "/v1/pipelines/runs/{id}/artifacts": {
      "get": {
        "operationId": "listPipelineArtifacts",
        "summary": "Files a native job kept (artifacts:)",
        "tags": [
          "Pipelines"
        ],
        "x-kosa8-scope": "sandboxes:read",
        "description": "Needs the `sandboxes:read` scope (or one that includes it).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Pipeline run id (prun_…)"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "artifacts": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "job": {
                            "type": "string"
                          },
                          "idx": {
                            "type": "integer"
                          },
                          "path": {
                            "type": "string"
                          },
                          "bytes": {
                            "type": "integer"
                          },
                          "url": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      }
    },
    "/v1/pipelines/runs/{id}/artifacts/{job}/{idx}": {
      "get": {
        "operationId": "getPipelineArtifact",
        "summary": "Download an artifact as .tar.gz",
        "tags": [
          "Pipelines"
        ],
        "x-kosa8-scope": "sandboxes:read",
        "description": "Needs the `sandboxes:read` scope (or one that includes it).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Pipeline run id (prun_…)"
          },
          {
            "name": "job",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Job name"
          },
          {
            "name": "idx",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The artifact's index in the job's artifacts:"
          }
        ],
        "responses": {
          "200": {
            "description": "The artifact",
            "content": {
              "application/gzip": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      }
    },
    "/v1/pipelines/hooks": {
      "get": {
        "operationId": "listPipelineHooks",
        "summary": "Webhook and schedule triggers (no secrets)",
        "tags": [
          "Pipelines"
        ],
        "x-kosa8-scope": "sandboxes:read",
        "description": "Needs the `sandboxes:read` scope (or one that includes it).",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "hooks": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "name": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "provider": {
                            "type": "string",
                            "enum": [
                              "github",
                              "gitlab"
                            ]
                          },
                          "repo_url": {
                            "type": "string"
                          },
                          "url": {
                            "type": "string",
                            "description": "Give this to the git host as the webhook URL (content type application/json)"
                          },
                          "secret": {
                            "type": "string",
                            "description": "Only when created: the webhook secret (GitHub) or token (GitLab)"
                          },
                          "size": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "secrets": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "token_secret": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "status_secret": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "workflow": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "timeout_s": {
                            "type": [
                              "integer",
                              "null"
                            ]
                          },
                          "cron": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "cron_ref": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "next_run_at": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "format": "date-time"
                          },
                          "deliveries": {
                            "type": "integer"
                          },
                          "last_delivery_at": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "format": "date-time"
                          },
                          "created_at": {
                            "type": "string",
                            "format": "date-time"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      },
      "post": {
        "operationId": "createPipelineHook",
        "summary": "Make a webhook URL for a repository's pushes and pull requests, and optionally a cron schedule",
        "tags": [
          "Pipelines"
        ],
        "x-kosa8-scope": "admin",
        "description": "Needs the `admin` scope (or one that includes it).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "repo_url": {
                    "type": "string"
                  },
                  "provider": {
                    "type": "string",
                    "enum": [
                      "github",
                      "gitlab"
                    ],
                    "description": "Default from repo_url's host"
                  },
                  "name": {
                    "type": "string"
                  },
                  "secret": {
                    "type": "string",
                    "minLength": 16,
                    "description": "Default: one is made and returned once"
                  },
                  "size": {
                    "type": "string"
                  },
                  "secrets": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "maxItems": 32,
                    "description": "kosa8 secret names (each made with pipelines: true); a job gets each as NAME_IN_CAPS"
                  },
                  "token_secret": {
                    "type": "string"
                  },
                  "status_secret": {
                    "type": "string"
                  },
                  "workflow": {
                    "type": "string"
                  },
                  "timeout_s": {
                    "type": "integer",
                    "minimum": 60,
                    "maximum": 21600
                  },
                  "cron": {
                    "type": "string",
                    "description": "m h dom mon dow (UTC): also run on this schedule"
                  },
                  "cron_ref": {
                    "type": "string",
                    "description": "The branch scheduled runs use (default main)"
                  }
                },
                "required": [
                  "repo_url"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "hook": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "name": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "provider": {
                          "type": "string",
                          "enum": [
                            "github",
                            "gitlab"
                          ]
                        },
                        "repo_url": {
                          "type": "string"
                        },
                        "url": {
                          "type": "string",
                          "description": "Give this to the git host as the webhook URL (content type application/json)"
                        },
                        "secret": {
                          "type": "string",
                          "description": "Only when created: the webhook secret (GitHub) or token (GitLab)"
                        },
                        "size": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "secrets": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "token_secret": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "status_secret": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "workflow": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "timeout_s": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "cron": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "cron_ref": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "next_run_at": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "deliveries": {
                          "type": "integer"
                        },
                        "last_delivery_at": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "created_at": {
                          "type": "string",
                          "format": "date-time"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          }
        }
      }
    },
    "/v1/pipelines/hooks/{id}": {
      "post": {
        "operationId": "deliverPipelineHook",
        "summary": "A git host's webhook delivery (no API key: GitHub's X-Hub-Signature-256 or GitLab's X-Gitlab-Token)",
        "tags": [
          "Pipelines"
        ],
        "description": "GitHub: push, pull_request (opened, synchronize, reopened) and ping. GitLab: Push Hook. Deliveries are deduplicated by X-GitHub-Delivery.",
        "security": [],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Hook id (phk_…)"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "ignored": {
                      "type": "string"
                    },
                    "duplicate": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "description": "Run queued",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "run_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      },
      "delete": {
        "operationId": "deletePipelineHook",
        "summary": "Delete a hook; its URL stops working",
        "tags": [
          "Pipelines"
        ],
        "x-kosa8-scope": "admin",
        "description": "Needs the `admin` scope (or one that includes it).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Hook id (phk_…)"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "deleted": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          }
        }
      }
    },
    "/v1/sandboxes/{id}/metrics": {
      "get": {
        "operationId": "getSandboxMetrics",
        "summary": "CPU, memory, disk and network use, read on the host",
        "tags": [
          "Observability"
        ],
        "x-kosa8-scope": "sandboxes:read",
        "description": "Needs the `sandboxes:read` scope (or one that includes it). Read from outside the VM: it never wakes a sleeping sandbox or keeps one awake. Takes about a quarter second.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Sandbox id (sbx_…)"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "metrics": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "state": {
                          "type": "string",
                          "description": "running, or sleeping (then only sleep_bytes is given)"
                        },
                        "cpus": {
                          "type": "integer"
                        },
                        "mem_mb": {
                          "type": "integer"
                        },
                        "disk_gb": {
                          "type": "integer"
                        },
                        "cpu_pct": {
                          "type": [
                            "number",
                            "null"
                          ],
                          "description": "CPU used over a quarter second, as a share of the sandbox's vCPUs (0-100). null where the host cannot read it"
                        },
                        "cpu_seconds": {
                          "type": [
                            "number",
                            "null"
                          ],
                          "description": "CPU time the VM has used since it booted"
                        },
                        "mem_bytes": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "description": "Host memory the VM holds: guest memory once touched, so it seldom falls"
                        },
                        "mem_pct": {
                          "type": [
                            "number",
                            "null"
                          ]
                        },
                        "disk_bytes": {
                          "type": "integer",
                          "description": "Space the sandbox's disks take on the host"
                        },
                        "net": {
                          "type": "object",
                          "properties": {
                            "out_frames": {
                              "type": "integer"
                            },
                            "out_bytes": {
                              "type": "integer",
                              "description": "Bytes the guest sent that its egress policy passed"
                            },
                            "in_frames": {
                              "type": "integer"
                            },
                            "in_bytes": {
                              "type": "integer",
                              "description": "Bytes delivered to the guest"
                            }
                          }
                        },
                        "egress_denied": {
                          "type": "integer",
                          "description": "Packets the egress policy refused since boot"
                        },
                        "sleep_bytes": {
                          "type": "integer"
                        },
                        "at": {
                          "type": "string",
                          "format": "date-time"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "501": {
            "$ref": "#/components/responses/E501"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      }
    },
    "/v1/sandboxes/{id}/logs": {
      "get": {
        "operationId": "getSandboxLogs",
        "summary": "The sandbox's last commands, with exit codes and output tails",
        "tags": [
          "Observability"
        ],
        "x-kosa8-scope": "sandboxes:read",
        "description": "Needs the `sandboxes:read` scope (or one that includes it). Kept on the sandbox's host, the newest 200, and removed with the sandbox.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Sandbox id (sbx_…)"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "entries": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "at": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "cmd": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "exit": {
                            "type": [
                              "integer",
                              "null"
                            ]
                          },
                          "ms": {
                            "type": "integer"
                          },
                          "stream": {
                            "type": "boolean"
                          },
                          "direct": {
                            "type": "boolean"
                          },
                          "stdout_tail": {
                            "type": "string",
                            "description": "The last 2 KiB of stdout"
                          },
                          "stderr_tail": {
                            "type": "string"
                          },
                          "error": {
                            "type": "string"
                          },
                          "oom": {
                            "type": "boolean",
                            "description": "Exit 137 and the guest's oom_kill counter rose: killed for memory. Absent when unknown"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "501": {
            "$ref": "#/components/responses/E501"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      }
    },
    "/v1/sandboxes/{id}/labels": {
      "put": {
        "operationId": "setSandboxLabels",
        "summary": "Replace the sandbox's labels (null clears them)",
        "tags": [
          "Observability"
        ],
        "x-kosa8-scope": "sandboxes:write",
        "description": "Needs the `sandboxes:write` scope (or one that includes it).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Sandbox id (sbx_…)"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "labels": {
                    "type": [
                      "object",
                      "null"
                    ],
                    "maxProperties": 16,
                    "additionalProperties": {
                      "type": "string",
                      "maxLength": 256
                    },
                    "description": "Up to 16 labels: keys of 1-63 letters, digits, '.', '_', '/' or '-'; string values up to 256 characters"
                  }
                },
                "required": [
                  "labels"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "labels": {
                      "type": "object",
                      "maxProperties": 16,
                      "additionalProperties": {
                        "type": "string",
                        "maxLength": 256
                      },
                      "description": "Up to 16 labels: keys of 1-63 letters, digits, '.', '_', '/' or '-'; string values up to 256 characters"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          }
        }
      }
    },
    "/v1/sandboxes/{id}/previews": {
      "get": {
        "operationId": "listPreviews",
        "summary": "The sandbox's preview URLs (no tokens)",
        "tags": [
          "Previews"
        ],
        "x-kosa8-scope": "sandboxes:read",
        "description": "Needs the `sandboxes:read` scope (or one that includes it).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Sandbox id (sbx_…)"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "previews": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "port": {
                            "type": "integer"
                          },
                          "public": {
                            "type": "boolean",
                            "description": "true: anyone with the URL may open it; false (default): a signed token is needed"
                          },
                          "url": {
                            "type": "string",
                            "description": "https://<slug>.<preview domain>/ — for a private preview, with ?kosa8_preview=<token>, which the first visit trades for a cookie"
                          },
                          "host": {
                            "type": "string"
                          },
                          "token": {
                            "type": "string",
                            "description": "Private previews only: send as X-Kosa8-Preview-Token from programs"
                          },
                          "expires_at": {
                            "type": "string",
                            "format": "date-time",
                            "description": "When the token and link stop working"
                          },
                          "created_at": {
                            "type": "integer"
                          },
                          "wake": {
                            "type": "boolean",
                            "description": "true: a request while the sandbox sleeps wakes it (payment and limits checked), held until it is awake"
                          },
                          "wake_per_hour": {
                            "type": "integer",
                            "description": "Most wakes this preview's sandbox takes from preview requests in a rolling hour (default 12)"
                          }
                        }
                      }
                    },
                    "configured": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      },
      "post": {
        "operationId": "openPreview",
        "summary": "Open a port at its own https URL, private (signed link) unless public: true",
        "tags": [
          "Previews"
        ],
        "x-kosa8-scope": "sandboxes:write",
        "description": "Needs the `sandboxes:write` scope (or one that includes it). The server must listen on 0.0.0.0, not 127.0.0.1. Opening a port that is already open answers 200 with a fresh link and applies public, wake and wake_per_hour. A sleeping sandbox's preview answers 503 until it is woken, unless wake is true: then the request wakes it (402 when the organization cannot pay for it, 429 past wake_per_hour).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Sandbox id (sbx_…)"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "port": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 65535
                  },
                  "public": {
                    "type": "boolean"
                  },
                  "expires_in_s": {
                    "type": "integer",
                    "minimum": 60,
                    "maximum": 604800,
                    "description": "How long the link works, in seconds (default 3600)"
                  },
                  "wake": {
                    "type": "boolean",
                    "description": "Wake the sandbox on a request while it sleeps (default false)"
                  },
                  "wake_per_hour": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 120,
                    "description": "Cap on wakes by preview requests per rolling hour (default 12)"
                  }
                },
                "required": [
                  "port"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "preview": {
                      "type": "object",
                      "properties": {
                        "port": {
                          "type": "integer"
                        },
                        "public": {
                          "type": "boolean",
                          "description": "true: anyone with the URL may open it; false (default): a signed token is needed"
                        },
                        "url": {
                          "type": "string",
                          "description": "https://<slug>.<preview domain>/ — for a private preview, with ?kosa8_preview=<token>, which the first visit trades for a cookie"
                        },
                        "host": {
                          "type": "string"
                        },
                        "token": {
                          "type": "string",
                          "description": "Private previews only: send as X-Kosa8-Preview-Token from programs"
                        },
                        "expires_at": {
                          "type": "string",
                          "format": "date-time",
                          "description": "When the token and link stop working"
                        },
                        "created_at": {
                          "type": "integer"
                        },
                        "wake": {
                          "type": "boolean",
                          "description": "true: a request while the sandbox sleeps wakes it (payment and limits checked), held until it is awake"
                        },
                        "wake_per_hour": {
                          "type": "integer",
                          "description": "Most wakes this preview's sandbox takes from preview requests in a rolling hour (default 12)"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "410": {
            "$ref": "#/components/responses/E410"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          },
          "501": {
            "$ref": "#/components/responses/E501"
          }
        }
      }
    },
    "/v1/sandboxes/{id}/previews/{port}/link": {
      "post": {
        "operationId": "previewLink",
        "summary": "A new signed link for a private preview",
        "tags": [
          "Previews"
        ],
        "x-kosa8-scope": "sandboxes:write",
        "description": "Needs the `sandboxes:write` scope (or one that includes it).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Sandbox id (sbx_…)"
          },
          {
            "name": "port",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The port in the sandbox, 1-65535"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "expires_in_s": {
                    "type": "integer",
                    "minimum": 60,
                    "maximum": 604800,
                    "description": "How long the link works, in seconds (default 3600)"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "preview": {
                      "type": "object",
                      "properties": {
                        "port": {
                          "type": "integer"
                        },
                        "public": {
                          "type": "boolean",
                          "description": "true: anyone with the URL may open it; false (default): a signed token is needed"
                        },
                        "url": {
                          "type": "string",
                          "description": "https://<slug>.<preview domain>/ — for a private preview, with ?kosa8_preview=<token>, which the first visit trades for a cookie"
                        },
                        "host": {
                          "type": "string"
                        },
                        "token": {
                          "type": "string",
                          "description": "Private previews only: send as X-Kosa8-Preview-Token from programs"
                        },
                        "expires_at": {
                          "type": "string",
                          "format": "date-time",
                          "description": "When the token and link stop working"
                        },
                        "created_at": {
                          "type": "integer"
                        },
                        "wake": {
                          "type": "boolean",
                          "description": "true: a request while the sandbox sleeps wakes it (payment and limits checked), held until it is awake"
                        },
                        "wake_per_hour": {
                          "type": "integer",
                          "description": "Most wakes this preview's sandbox takes from preview requests in a rolling hour (default 12)"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          },
          "501": {
            "$ref": "#/components/responses/E501"
          }
        }
      }
    },
    "/v1/sandboxes/{id}/previews/{port}/rotate": {
      "post": {
        "operationId": "rotatePreview",
        "summary": "Move the preview to a new address, ending every earlier link and cookie",
        "tags": [
          "Previews"
        ],
        "x-kosa8-scope": "sandboxes:write",
        "description": "Needs the `sandboxes:write` scope (or one that includes it).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Sandbox id (sbx_…)"
          },
          {
            "name": "port",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The port in the sandbox, 1-65535"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "expires_in_s": {
                    "type": "integer",
                    "minimum": 60,
                    "maximum": 604800,
                    "description": "How long the link works, in seconds (default 3600)"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "preview": {
                      "type": "object",
                      "properties": {
                        "port": {
                          "type": "integer"
                        },
                        "public": {
                          "type": "boolean",
                          "description": "true: anyone with the URL may open it; false (default): a signed token is needed"
                        },
                        "url": {
                          "type": "string",
                          "description": "https://<slug>.<preview domain>/ — for a private preview, with ?kosa8_preview=<token>, which the first visit trades for a cookie"
                        },
                        "host": {
                          "type": "string"
                        },
                        "token": {
                          "type": "string",
                          "description": "Private previews only: send as X-Kosa8-Preview-Token from programs"
                        },
                        "expires_at": {
                          "type": "string",
                          "format": "date-time",
                          "description": "When the token and link stop working"
                        },
                        "created_at": {
                          "type": "integer"
                        },
                        "wake": {
                          "type": "boolean",
                          "description": "true: a request while the sandbox sleeps wakes it (payment and limits checked), held until it is awake"
                        },
                        "wake_per_hour": {
                          "type": "integer",
                          "description": "Most wakes this preview's sandbox takes from preview requests in a rolling hour (default 12)"
                        }
                      }
                    },
                    "revoked_host": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "501": {
            "$ref": "#/components/responses/E501"
          }
        }
      }
    },
    "/v1/sandboxes/{id}/previews/{port}": {
      "delete": {
        "operationId": "closePreview",
        "summary": "Close the port's preview",
        "tags": [
          "Previews"
        ],
        "x-kosa8-scope": "sandboxes:write",
        "description": "Needs the `sandboxes:write` scope (or one that includes it).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Sandbox id (sbx_…)"
          },
          {
            "name": "port",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The port in the sandbox, 1-65535"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "deleted": {
                      "type": "boolean"
                    },
                    "port": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      }
    },
    "/v1/egress/presets": {
      "get": {
        "operationId": "listEgressPresets",
        "summary": "Named sets of package-registry hosts for egress allow lists",
        "tags": [
          "Egress"
        ],
        "x-kosa8-scope": "sandboxes:read",
        "description": "Needs the `sandboxes:read` scope (or one that includes it).",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "presets": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      }
    },
    "/v1/sandboxes/{id}/egress": {
      "get": {
        "operationId": "getSandboxEgress",
        "summary": "The egress policy the sandbox runs with",
        "tags": [
          "Egress"
        ],
        "x-kosa8-scope": "sandboxes:read",
        "description": "Needs the `sandboxes:read` scope (or one that includes it).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Sandbox id (sbx_…)"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "egress": {
                      "type": "object",
                      "properties": {
                        "internet": {
                          "type": "boolean"
                        },
                        "allow": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "Hostnames (exact), *.domain wildcards (any depth below, not the domain), IPv4 addresses or CIDRs"
                        },
                        "deny": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "Hostnames (exact), *.domain wildcards (any depth below, not the domain), IPv4 addresses or CIDRs"
                        },
                        "presets": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "source": {
                          "type": "string",
                          "enum": [
                            "sandbox",
                            "org",
                            "default"
                          ]
                        },
                        "enforced": {
                          "type": "string",
                          "description": "The policy the host enforces: any, deny, allow:…[;deny:…] or block:…"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      },
      "put": {
        "operationId": "setSandboxEgress",
        "summary": "Change what the sandbox may reach, at once (a sleeping one when it wakes)",
        "tags": [
          "Egress"
        ],
        "x-kosa8-scope": "sandboxes:write",
        "description": "Needs the `sandboxes:write` scope (or one that includes it). Inside the organization's policy when it enforces one (403 egress_not_allowed otherwise). Connections the new policy refuses stop at their next packet.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Sandbox id (sbx_…)"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "internet": {
                    "type": "boolean",
                    "description": "false: nothing leaves but what allow and presets name. Default true when nothing is listed"
                  },
                  "allow": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Hostnames (exact), *.domain wildcards (any depth below, not the domain), IPv4 addresses or CIDRs"
                  },
                  "deny": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Refused even where allow covers them. A name is refused at DNS; a CIDR for every packet"
                  },
                  "presets": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "common",
                        "npm",
                        "pypi",
                        "github",
                        "go",
                        "crates",
                        "rubygems",
                        "maven",
                        "apt",
                        "alpine",
                        "docker",
                        "huggingface",
                        "ai"
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "egress": {
                      "type": "object",
                      "properties": {
                        "internet": {
                          "type": "boolean"
                        },
                        "allow": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "Hostnames (exact), *.domain wildcards (any depth below, not the domain), IPv4 addresses or CIDRs"
                        },
                        "deny": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "Hostnames (exact), *.domain wildcards (any depth below, not the domain), IPv4 addresses or CIDRs"
                        },
                        "presets": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "source": {
                          "type": "string",
                          "enum": [
                            "sandbox",
                            "org",
                            "default"
                          ]
                        },
                        "enforced": {
                          "type": "string",
                          "description": "The policy the host enforces: any, deny, allow:…[;deny:…] or block:…"
                        }
                      }
                    },
                    "applied": {
                      "type": "boolean"
                    },
                    "sleeping": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          },
          "501": {
            "$ref": "#/components/responses/E501"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      },
      "delete": {
        "operationId": "resetSandboxEgress",
        "summary": "Back to the organization's default",
        "tags": [
          "Egress"
        ],
        "x-kosa8-scope": "sandboxes:write",
        "description": "Needs the `sandboxes:write` scope (or one that includes it).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Sandbox id (sbx_…)"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "egress": {
                      "type": "object",
                      "properties": {
                        "internet": {
                          "type": "boolean"
                        },
                        "allow": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "Hostnames (exact), *.domain wildcards (any depth below, not the domain), IPv4 addresses or CIDRs"
                        },
                        "deny": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "Hostnames (exact), *.domain wildcards (any depth below, not the domain), IPv4 addresses or CIDRs"
                        },
                        "presets": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "source": {
                          "type": "string",
                          "enum": [
                            "sandbox",
                            "org",
                            "default"
                          ]
                        },
                        "enforced": {
                          "type": "string",
                          "description": "The policy the host enforces: any, deny, allow:…[;deny:…] or block:…"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          },
          "501": {
            "$ref": "#/components/responses/E501"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          }
        }
      }
    },
    "/v1/org/egress": {
      "get": {
        "operationId": "getOrgEgress",
        "summary": "The organization's egress default and whether it is enforced",
        "tags": [
          "Egress"
        ],
        "x-kosa8-scope": "sandboxes:read",
        "description": "Needs the `sandboxes:read` scope (or one that includes it).",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "egress": {
                      "type": [
                        "object",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      },
      "put": {
        "operationId": "setOrgEgress",
        "summary": "Set the organization's egress default (enforce: true makes it a ceiling); pushed to running and sleeping sandboxes",
        "tags": [
          "Egress"
        ],
        "x-kosa8-scope": "admin",
        "description": "Needs the `admin` scope (or one that includes it).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "default": {
                    "type": [
                      "object",
                      "null"
                    ],
                    "properties": {
                      "internet": {
                        "type": "boolean",
                        "description": "false: nothing leaves but what allow and presets name. Default true when nothing is listed"
                      },
                      "allow": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "description": "Hostnames (exact), *.domain wildcards (any depth below, not the domain), IPv4 addresses or CIDRs"
                      },
                      "deny": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "description": "Refused even where allow covers them. A name is refused at DNS; a CIDR for every packet"
                      },
                      "presets": {
                        "type": "array",
                        "items": {
                          "type": "string",
                          "enum": [
                            "common",
                            "npm",
                            "pypi",
                            "github",
                            "go",
                            "crates",
                            "rubygems",
                            "maven",
                            "apt",
                            "alpine",
                            "docker",
                            "huggingface",
                            "ai"
                          ]
                        }
                      }
                    }
                  },
                  "enforce": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "default"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "egress": {
                      "type": [
                        "object",
                        "null"
                      ]
                    },
                    "applied": {
                      "type": "integer"
                    },
                    "failed": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          }
        }
      }
    },
    "/v1/secrets": {
      "get": {
        "operationId": "listSecrets",
        "summary": "The organization's secrets: names and where each goes, never values",
        "tags": [
          "Secrets"
        ],
        "x-kosa8-scope": "sandboxes:read",
        "description": "Needs the `sandboxes:read` scope (or one that includes it).",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "secrets": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "name": {
                            "type": "string"
                          },
                          "upstream": {
                            "type": "string",
                            "description": "https://host[:port]: the only place the value is sent"
                          },
                          "header": {
                            "type": "string"
                          },
                          "scheme": {
                            "type": "string"
                          },
                          "methods": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "paths": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "env": {
                            "type": "object",
                            "additionalProperties": {
                              "type": "string"
                            },
                            "description": "What the sandbox is given; {{url}} is the broker's address for this secret, {{placeholder}} its stand-in"
                          },
                          "pipelines": {
                            "type": "boolean",
                            "description": "true: kosa8 Pipelines may give the value itself to a CI job"
                          },
                          "created_at": {
                            "type": "integer"
                          },
                          "updated_at": {
                            "type": "integer"
                          },
                          "last_used_at": {
                            "type": [
                              "integer",
                              "null"
                            ]
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      }
    },
    "/v1/secrets/{name}": {
      "put": {
        "operationId": "putSecret",
        "summary": "Store (or replace) a secret, encrypted; sandboxes created with it hold only a placeholder",
        "tags": [
          "Secrets"
        ],
        "x-kosa8-scope": "admin",
        "description": "Needs the `admin` scope (or one that includes it). Answers 200 when it replaces one. Sandboxes already running keep the value they were created with.",
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Secret name: 1-32 of a-z, 0-9 and -"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "value": {
                    "type": "string",
                    "maxLength": 8192,
                    "description": "The real key or token. Stored encrypted; never returned"
                  },
                  "upstream": {
                    "type": "string",
                    "description": "https://host[:port], no path"
                  },
                  "header": {
                    "type": "string",
                    "description": "Header that carries it upstream (default Authorization)"
                  },
                  "scheme": {
                    "type": "string",
                    "description": "Written before the value (default \"Bearer \" for Authorization, else none)"
                  },
                  "methods": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "HTTP methods it may be used with; empty: any but TRACE"
                  },
                  "paths": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Upstream path prefixes it may be used on; empty: any"
                  },
                  "env": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "string"
                    },
                    "description": "Default {NAME_API_KEY: \"{{placeholder}}\", NAME_BASE_URL: \"{{url}}\"}"
                  },
                  "pipelines": {
                    "type": "boolean",
                    "description": "Default false. true: a pipeline run that names it gets the value itself, as an environment variable of its jobs (npm-token is NPM_TOKEN), as CI secrets are; never in a sandbox otherwise"
                  }
                },
                "required": [
                  "value",
                  "upstream"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "secret": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string"
                        },
                        "upstream": {
                          "type": "string",
                          "description": "https://host[:port]: the only place the value is sent"
                        },
                        "header": {
                          "type": "string"
                        },
                        "scheme": {
                          "type": "string"
                        },
                        "methods": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "paths": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "env": {
                          "type": "object",
                          "additionalProperties": {
                            "type": "string"
                          },
                          "description": "What the sandbox is given; {{url}} is the broker's address for this secret, {{placeholder}} its stand-in"
                        },
                        "pipelines": {
                          "type": "boolean",
                          "description": "true: kosa8 Pipelines may give the value itself to a CI job"
                        },
                        "created_at": {
                          "type": "integer"
                        },
                        "updated_at": {
                          "type": "integer"
                        },
                        "last_used_at": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        }
                      }
                    },
                    "replaced": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          }
        }
      },
      "delete": {
        "operationId": "deleteSecret",
        "summary": "Delete a secret; sandboxes holding it keep it until they are deleted",
        "tags": [
          "Secrets"
        ],
        "x-kosa8-scope": "admin",
        "description": "Needs the `admin` scope (or one that includes it).",
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Secret name: 1-32 of a-z, 0-9 and -"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "deleted": {
                      "type": "string"
                    },
                    "still_held_by": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          }
        }
      }
    },
    "/v1/sandboxes/{id}/secrets": {
      "get": {
        "operationId": "getSandboxSecrets",
        "summary": "Which secrets the sandbox was created with",
        "tags": [
          "Secrets"
        ],
        "x-kosa8-scope": "sandboxes:read",
        "description": "Needs the `sandboxes:read` scope (or one that includes it).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Sandbox id (sbx_…)"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "secrets": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      }
    },
    "/v1/sandboxes/{id}/terminal": {
      "post": {
        "operationId": "openTerminal",
        "summary": "A wss:// URL for an interactive terminal (PTY) in the sandbox",
        "tags": [
          "Terminal and large files"
        ],
        "x-kosa8-scope": "sandboxes:write",
        "description": "Needs the `sandboxes:write` scope (or one that includes it). The terminal is a fresh container from the sandbox's image with /workspace mounted. Binary WebSocket messages are keys in and output out; text messages are JSON: {type: \"resize\", cols, rows} in, {type: \"exit\", code} out. A sleeping sandbox is woken first.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Sandbox id (sbx_…)"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "cols": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 1000
                  },
                  "rows": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 1000
                  },
                  "command": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Run this instead of a login shell, e.g. [\"python3\"]"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "terminal": {
                      "type": "object",
                      "properties": {
                        "url": {
                          "type": "string",
                          "description": "wss:// URL on the sandbox's host, token included; connect before expires_at"
                        },
                        "expires_at": {
                          "type": "integer",
                          "description": "ms since the epoch; a connected terminal stays open after it"
                        },
                        "protocol": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          },
          "501": {
            "$ref": "#/components/responses/E501"
          }
        }
      }
    },
    "/v1/sandboxes/{id}/files/link": {
      "post": {
        "operationId": "fileLink",
        "summary": "A presigned URL for one download (GET) or upload (PUT) of one path, straight to the host",
        "tags": [
          "Terminal and large files"
        ],
        "x-kosa8-scope": "sandboxes:read",
        "description": "Needs the `sandboxes:read` scope (or one that includes it). PUT links need sandboxes:write. No size cap but the sandbox's disk (4 GiB per upload). A sleeping sandbox is woken first; a link used after it falls asleep again answers 409 use_api.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Sandbox id (sbx_…)"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "path": {
                    "type": "string"
                  },
                  "method": {
                    "type": "string",
                    "enum": [
                      "GET",
                      "PUT"
                    ]
                  },
                  "ttl_s": {
                    "type": "integer",
                    "minimum": 10,
                    "maximum": 300
                  }
                },
                "required": [
                  "path"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "link": {
                      "type": "object",
                      "properties": {
                        "url": {
                          "type": "string",
                          "description": "The host's URL with a token for this one method and path; needs no other credential"
                        },
                        "method": {
                          "type": "string",
                          "enum": [
                            "GET",
                            "PUT"
                          ]
                        },
                        "path": {
                          "type": "string"
                        },
                        "expires_at": {
                          "type": "integer",
                          "description": "ms since the epoch; the host refuses the link after it (at most 300 s)"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          },
          "501": {
            "$ref": "#/components/responses/E501"
          }
        }
      }
    },
    "/v1/sandboxes/{id}/files/raw": {
      "get": {
        "operationId": "readFileRaw",
        "summary": "The file's bytes, streamed (the same as GET …/files on a host that streams)",
        "tags": [
          "Terminal and large files"
        ],
        "x-kosa8-scope": "sandboxes:read",
        "description": "Needs the `sandboxes:read` scope (or one that includes it).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Sandbox id (sbx_…)"
          },
          {
            "name": "path",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "An absolute path in the sandbox such as /workspace/data.csv or /tmp/out.bin (no ..)"
          },
          {
            "name": "Range",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "One byte range (bytes=a-b, a-, -n): 206 with Content-Range, 416 past the end"
          }
        ],
        "responses": {
          "200": {
            "description": "The file",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "416": {
            "$ref": "#/components/responses/E416"
          },
          "501": {
            "$ref": "#/components/responses/E501"
          }
        }
      },
      "put": {
        "operationId": "writeFileRaw",
        "summary": "Write the request body to the file, streamed (the same as PUT …/files on a host that streams)",
        "tags": [
          "Terminal and large files"
        ],
        "x-kosa8-scope": "sandboxes:write",
        "description": "Needs the `sandboxes:write` scope (or one that includes it). Through this API an upload is bounded by the request size Cloudflare allows (100 MB on most plans); past that, send parts with offset=, or PUT to the direct files_url or a PUT link, which go to the host straight (4 GiB a request).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Sandbox id (sbx_…)"
          },
          {
            "name": "path",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "An absolute path in the sandbox such as /workspace/data.csv or /tmp/out.bin (no ..)"
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0
            },
            "description": "Write the body at this byte; the rest of the file is kept and it grows as needed"
          },
          {
            "name": "append",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "1",
                "true"
              ]
            },
            "description": "Add the body at the end (not with offset)"
          },
          {
            "name": "mode",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[0-7]{3,4}$"
            },
            "description": "Permission bits, octal"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/octet-stream": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "file": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "413": {
            "$ref": "#/components/responses/E413"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          },
          "501": {
            "$ref": "#/components/responses/E501"
          },
          "507": {
            "$ref": "#/components/responses/E507"
          }
        }
      }
    },
    "/v1/sandboxes/{id}/schedules": {
      "get": {
        "operationId": "listSchedules",
        "summary": "The sandbox's schedules, each with its last run",
        "tags": [
          "Schedules"
        ],
        "x-kosa8-scope": "sandboxes:read",
        "description": "Needs the `sandboxes:read` scope (or one that includes it).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Sandbox id (sbx_…)"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "schedules": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "sandbox_id": {
                            "type": "string"
                          },
                          "name": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "cron": {
                            "type": "string",
                            "description": "Five fields, UTC: minute hour day-of-month month day-of-week"
                          },
                          "cmd": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "env_names": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "wake": {
                            "type": "boolean"
                          },
                          "next_run_at": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "format": "date-time"
                          },
                          "runs": {
                            "type": "integer"
                          },
                          "created_at": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "last_run": {
                            "type": [
                              "object",
                              "null"
                            ],
                            "properties": {
                              "at": {
                                "type": "string",
                                "format": "date-time"
                              },
                              "status": {
                                "type": "string",
                                "enum": [
                                  "ok",
                                  "failed",
                                  "skipped"
                                ]
                              },
                              "exit": {
                                "type": [
                                  "integer",
                                  "null"
                                ]
                              },
                              "error": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "output": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "stdout then stderr, last 4 KiB"
                              },
                              "ms": {
                                "type": [
                                  "integer",
                                  "null"
                                ]
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      },
      "post": {
        "operationId": "createSchedule",
        "summary": "Run a command in the sandbox on a cron schedule (UTC)",
        "tags": [
          "Schedules"
        ],
        "x-kosa8-scope": "sandboxes:write",
        "description": "Needs the `sandboxes:write` scope (or one that includes it). Run by the control plane's minute tick as a buffered exec (stopped at 90 s). A run that would wake the sandbox is held to the wake rules (payment, spending cap, running limit); one refused is recorded as skipped. At most 10 per sandbox.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Sandbox id (sbx_…)"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "cron": {
                    "type": "string",
                    "example": "*/15 * * * *"
                  },
                  "cmd": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "env": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "NAME=value"
                  },
                  "name": {
                    "type": "string",
                    "maxLength": 64
                  },
                  "wake": {
                    "type": "boolean",
                    "description": "Wake the sandbox for a run due while it sleeps (default true); false skips that run"
                  }
                },
                "required": [
                  "cron",
                  "cmd"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "schedule": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "sandbox_id": {
                          "type": "string"
                        },
                        "name": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "cron": {
                          "type": "string",
                          "description": "Five fields, UTC: minute hour day-of-month month day-of-week"
                        },
                        "cmd": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "env_names": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "wake": {
                          "type": "boolean"
                        },
                        "next_run_at": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "runs": {
                          "type": "integer"
                        },
                        "created_at": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "last_run": {
                          "type": [
                            "object",
                            "null"
                          ],
                          "properties": {
                            "at": {
                              "type": "string",
                              "format": "date-time"
                            },
                            "status": {
                              "type": "string",
                              "enum": [
                                "ok",
                                "failed",
                                "skipped"
                              ]
                            },
                            "exit": {
                              "type": [
                                "integer",
                                "null"
                              ]
                            },
                            "error": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "output": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "description": "stdout then stderr, last 4 KiB"
                            },
                            "ms": {
                              "type": [
                                "integer",
                                "null"
                              ]
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          }
        }
      }
    },
    "/v1/sandboxes/{id}/schedules/{sid}": {
      "delete": {
        "operationId": "deleteSchedule",
        "summary": "Stop and remove a schedule",
        "tags": [
          "Schedules"
        ],
        "x-kosa8-scope": "sandboxes:write",
        "description": "Needs the `sandboxes:write` scope (or one that includes it).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Sandbox id (sbx_…)"
          },
          {
            "name": "sid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Schedule id (sch_…)"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "deleted": {
                      "type": "boolean"
                    },
                    "id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          }
        }
      }
    },
    "/v1/sandboxes/{id}/schedules/{sid}/run": {
      "post": {
        "operationId": "runSchedule",
        "summary": "Run a schedule now, under the same rules; its next time is unchanged",
        "tags": [
          "Schedules"
        ],
        "x-kosa8-scope": "sandboxes:write",
        "description": "Needs the `sandboxes:write` scope (or one that includes it).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Sandbox id (sbx_…)"
          },
          {
            "name": "sid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Schedule id (sch_…)"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "schedule": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "sandbox_id": {
                          "type": "string"
                        },
                        "name": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "cron": {
                          "type": "string",
                          "description": "Five fields, UTC: minute hour day-of-month month day-of-week"
                        },
                        "cmd": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "env_names": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "wake": {
                          "type": "boolean"
                        },
                        "next_run_at": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "runs": {
                          "type": "integer"
                        },
                        "created_at": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "last_run": {
                          "type": [
                            "object",
                            "null"
                          ],
                          "properties": {
                            "at": {
                              "type": "string",
                              "format": "date-time"
                            },
                            "status": {
                              "type": "string",
                              "enum": [
                                "ok",
                                "failed",
                                "skipped"
                              ]
                            },
                            "exit": {
                              "type": [
                                "integer",
                                "null"
                              ]
                            },
                            "error": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "output": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "description": "stdout then stderr, last 4 KiB"
                            },
                            "ms": {
                              "type": [
                                "integer",
                                "null"
                              ]
                            }
                          }
                        }
                      }
                    },
                    "run": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string"
                        },
                        "exit": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "error": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "output": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "ms": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          }
        }
      }
    },
    "/v1/sandboxes/{id}/code": {
      "post": {
        "operationId": "runCode",
        "summary": "Run a Python cell in a stateful context: globals persist between calls, charts come back as images",
        "tags": [
          "Code interpreter"
        ],
        "x-kosa8-scope": "sandboxes:write",
        "description": "Needs the `sandboxes:write` scope (or one that includes it). Needs a persistent sandbox (409 not_persistent otherwise) whose image has python3 (409 no_python). Runs through exec: a sleeping sandbox is woken first, with the same payment checks.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Sandbox id (sbx_…)"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string",
                    "maxLength": 40960
                  },
                  "language": {
                    "type": "string",
                    "enum": [
                      "python"
                    ]
                  },
                  "context": {
                    "type": "string",
                    "description": "Default \"default\"; started on first use"
                  },
                  "timeout_s": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 80,
                    "description": "Default 30. Past it the cell is interrupted (TimeoutError) and the context lives on"
                  }
                },
                "required": [
                  "code"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "context": {
                      "type": "string"
                    },
                    "execution_count": {
                      "type": "integer"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "type": {
                            "type": "string",
                            "enum": [
                              "text",
                              "image/png",
                              "image/svg+xml",
                              "html",
                              "json"
                            ]
                          },
                          "data": {
                            "description": "image/png: base64; json: the value; otherwise a string"
                          },
                          "name": {
                            "type": "string",
                            "description": "For a matplotlib figure: figure-N.png"
                          }
                        }
                      },
                      "description": "The last expression's value, each display(obj), then each matplotlib figure left open"
                    },
                    "stdout": {
                      "type": "string"
                    },
                    "stderr": {
                      "type": "string"
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string"
                        },
                        "value": {
                          "type": "string"
                        },
                        "traceback": {
                          "type": "string"
                        }
                      }
                    },
                    "truncated": {
                      "type": "boolean",
                      "description": "Results past 1 MiB were left out"
                    },
                    "woke_ms": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          },
          "504": {
            "$ref": "#/components/responses/E504"
          }
        }
      }
    },
    "/v1/sandboxes/{id}/code/contexts": {
      "get": {
        "operationId": "listCodeContexts",
        "summary": "The sandbox's running code contexts",
        "tags": [
          "Code interpreter"
        ],
        "x-kosa8-scope": "sandboxes:write",
        "description": "Needs the `sandboxes:write` scope (or one that includes it). Needs a persistent sandbox (409 not_persistent otherwise) whose image has python3 (409 no_python). Runs through exec: a sleeping sandbox is woken first, with the same payment checks.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Sandbox id (sbx_…)"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "contexts": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "name": {
                            "type": "string"
                          },
                          "execution_count": {
                            "type": "integer"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          }
        }
      },
      "post": {
        "operationId": "createCodeContext",
        "summary": "Start a context (its own globals)",
        "tags": [
          "Code interpreter"
        ],
        "x-kosa8-scope": "sandboxes:write",
        "description": "Needs the `sandboxes:write` scope (or one that includes it). Needs a persistent sandbox (409 not_persistent otherwise) whose image has python3 (409 no_python). Runs through exec: a sleeping sandbox is woken first, with the same payment checks.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Sandbox id (sbx_…)"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "context": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string"
                        },
                        "execution_count": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          }
        }
      }
    },
    "/v1/sandboxes/{id}/code/contexts/{name}/reset": {
      "post": {
        "operationId": "resetCodeContext",
        "summary": "Forget a context's globals",
        "tags": [
          "Code interpreter"
        ],
        "x-kosa8-scope": "sandboxes:write",
        "description": "Needs the `sandboxes:write` scope (or one that includes it).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Sandbox id (sbx_…)"
          },
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Context name: 1-32 of a-z, 0-9 and -"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "reset": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          }
        }
      }
    },
    "/v1/sandboxes/{id}/code/contexts/{name}": {
      "delete": {
        "operationId": "deleteCodeContext",
        "summary": "End a context's process",
        "tags": [
          "Code interpreter"
        ],
        "x-kosa8-scope": "sandboxes:write",
        "description": "Needs the `sandboxes:write` scope (or one that includes it).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Sandbox id (sbx_…)"
          },
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Context name: 1-32 of a-z, 0-9 and -"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "deleted": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          }
        }
      }
    },
    "/v1/threats": {
      "get": {
        "operationId": "listThreats",
        "summary": "The organization's threat feed: hosts every sandbox is refused",
        "tags": [
          "Threat feed"
        ],
        "x-kosa8-scope": "sandboxes:read",
        "description": "Needs the `sandboxes:read` scope (or one that includes it).",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "threats": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "description": "thr_…"
                          },
                          "host": {
                            "type": "string",
                            "description": "Hostname, *.domain, IPv4 address or CIDR, as enforced"
                          },
                          "reason": {
                            "type": "string"
                          },
                          "source": {
                            "type": "string",
                            "enum": [
                              "analyst",
                              "lab",
                              "anomaly",
                              "api"
                            ]
                          },
                          "sandbox": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The sandbox that flagged it (same as sandbox_id)"
                          },
                          "sandbox_id": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "created_by": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "member:EMAIL or key:ID"
                          },
                          "created_at": {
                            "type": "integer",
                            "description": "Unix ms"
                          }
                        }
                      }
                    },
                    "max": {
                      "type": "integer"
                    },
                    "unblock": {
                      "type": "object",
                      "properties": {
                        "scope": {
                          "type": "string",
                          "description": "The scope an unblock needs"
                        },
                        "allowed": {
                          "type": "boolean",
                          "description": "Whether this caller may unblock"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      },
      "post": {
        "operationId": "blockThreat",
        "summary": "Block a host for every sandbox of the organization, at once",
        "tags": [
          "Threat feed"
        ],
        "x-kosa8-scope": "sandboxes:write",
        "description": "Needs the `sandboxes:write` scope (or one that includes it). Added as a deny to every sandbox's egress policy, its own or the organization's; an open policy becomes block:…. Sent to every running and sleeping sandbox within seconds of the answer, and applied at create to new ones. Answers 200 with created: false when the host is already blocked. At most 100 hosts (409 threat_feed_full).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "host": {
                    "type": "string",
                    "description": "Hostname (exact), *.domain, IPv4 address or CIDR"
                  },
                  "reason": {
                    "type": "string",
                    "maxLength": 500
                  },
                  "sandbox_id": {
                    "type": "string",
                    "description": "The sandbox that flagged it"
                  },
                  "source": {
                    "type": "string",
                    "enum": [
                      "anomaly"
                    ],
                    "description": "Recorded as analyst for a person and api for a key; only anomaly may be given, with sandbox_id"
                  }
                },
                "required": [
                  "host"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "threat": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "description": "thr_…"
                        },
                        "host": {
                          "type": "string",
                          "description": "Hostname, *.domain, IPv4 address or CIDR, as enforced"
                        },
                        "reason": {
                          "type": "string"
                        },
                        "source": {
                          "type": "string",
                          "enum": [
                            "analyst",
                            "lab",
                            "anomaly",
                            "api"
                          ]
                        },
                        "sandbox": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The sandbox that flagged it (same as sandbox_id)"
                        },
                        "sandbox_id": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "created_by": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "member:EMAIL or key:ID"
                        },
                        "created_at": {
                          "type": "integer",
                          "description": "Unix ms"
                        }
                      }
                    },
                    "created": {
                      "type": "boolean"
                    },
                    "pushing": {
                      "type": "object",
                      "properties": {
                        "sandboxes": {
                          "type": "integer",
                          "description": "Running and sleeping sandboxes the new policy was sent to (up to 500)"
                        },
                        "applied": {
                          "type": "integer",
                          "description": "How many of them their host applied it on"
                        },
                        "failed": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "Sandboxes whose host refused or could not be reached: they still run without this change (up to 100 ids)"
                        },
                        "not_pushed": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          }
        }
      }
    },
    "/v1/threats/{id}": {
      "delete": {
        "operationId": "unblockThreat",
        "summary": "Unblock a host everywhere",
        "tags": [
          "Threat feed"
        ],
        "x-kosa8-scope": "admin",
        "description": "Needs the `admin` scope (or one that includes it). Unblocking gives access back, so it needs admin, the scope that sets the organization's egress policy.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The entry's id (thr_…) or its host, URL-encoded"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "deleted": {
                      "type": "string"
                    },
                    "host": {
                      "type": "string"
                    },
                    "pushing": {
                      "type": "object",
                      "properties": {
                        "sandboxes": {
                          "type": "integer",
                          "description": "Running and sleeping sandboxes the new policy was sent to (up to 500)"
                        },
                        "applied": {
                          "type": "integer",
                          "description": "How many of them their host applied it on"
                        },
                        "failed": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "Sandboxes whose host refused or could not be reached: they still run without this change (up to 100 ids)"
                        },
                        "not_pushed": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          }
        }
      }
    },
    "/v1/swarms": {
      "get": {
        "operationId": "listSwarms",
        "summary": "The organization's swarms, newest first, without counters",
        "tags": [
          "Swarms"
        ],
        "x-kosa8-scope": "sandboxes:read",
        "description": "Needs the `sandboxes:read` scope (or one that includes it).",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "swarms": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "description": "swm_…"
                          },
                          "name": {
                            "type": "string"
                          },
                          "parent": {
                            "type": "string",
                            "description": "The sandbox the members were forked from"
                          },
                          "start_checkpoint": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The parent's checkpoint taken at creation"
                          },
                          "created_at": {
                            "type": "integer"
                          },
                          "created_by": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "killed_at": {
                            "type": [
                              "integer",
                              "null"
                            ]
                          },
                          "state": {
                            "type": "string",
                            "enum": [
                              "running",
                              "paused",
                              "killed",
                              "mixed"
                            ]
                          },
                          "policy": {
                            "type": [
                              "object",
                              "null"
                            ],
                            "properties": {
                              "internet": {
                                "type": "boolean"
                              },
                              "allow": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                },
                                "description": "Hostnames (exact), *.domain wildcards (any depth below, not the domain), IPv4 addresses or CIDRs"
                              },
                              "deny": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                },
                                "description": "Hostnames (exact), *.domain wildcards (any depth below, not the domain), IPv4 addresses or CIDRs"
                              },
                              "presets": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              },
                              "source": {
                                "type": "string",
                                "enum": [
                                  "sandbox",
                                  "org",
                                  "default"
                                ]
                              },
                              "enforced": {
                                "type": "string",
                                "description": "The policy the host enforces: any, deny, allow:…[;deny:…] or block:…"
                              }
                            }
                          },
                          "counts": {
                            "type": "object",
                            "properties": {
                              "members": {
                                "type": "integer"
                              },
                              "running": {
                                "type": "integer"
                              },
                              "paused": {
                                "type": "integer"
                              },
                              "gone": {
                                "type": "integer"
                              },
                              "anomalies": {
                                "type": "integer"
                              }
                            }
                          },
                          "members": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "id": {
                                  "type": "string"
                                },
                                "name": {
                                  "type": "string",
                                  "description": "<swarm>-<n>"
                                },
                                "state": {
                                  "type": "string",
                                  "description": "The sandbox's state: running, sleeping, creating, deleted, …"
                                },
                                "egress": {
                                  "type": "object",
                                  "properties": {
                                    "allowed": {
                                      "type": [
                                        "integer",
                                        "null"
                                      ],
                                      "description": "Always null on kosa8 Cloud: the host does not report it"
                                    },
                                    "denied": {
                                      "type": [
                                        "integer",
                                        "null"
                                      ],
                                      "description": "Packets refused by egress since the member last booted; null when not read"
                                    },
                                    "bytes_out": {
                                      "type": [
                                        "integer",
                                        "null"
                                      ]
                                    },
                                    "hosts": {
                                      "type": "array",
                                      "items": {
                                        "type": "string"
                                      },
                                      "description": "Always empty on kosa8 Cloud"
                                    }
                                  }
                                },
                                "anomalies": {
                                  "type": "array",
                                  "items": {
                                    "type": "object",
                                    "properties": {
                                      "kind": {
                                        "type": "string",
                                        "enum": [
                                          "rare_host",
                                          "egress_spike",
                                          "denied_burst"
                                        ]
                                      },
                                      "member": {
                                        "type": "string",
                                        "description": "Sandbox id"
                                      },
                                      "member_name": {
                                        "type": [
                                          "string",
                                          "null"
                                        ]
                                      },
                                      "detail": {
                                        "type": "string"
                                      },
                                      "host": {
                                        "type": [
                                          "string",
                                          "null"
                                        ]
                                      },
                                      "first_seen": {
                                        "type": "integer",
                                        "description": "Unix ms"
                                      }
                                    }
                                  }
                                }
                              }
                            }
                          },
                          "anomalies": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "kind": {
                                  "type": "string",
                                  "enum": [
                                    "rare_host",
                                    "egress_spike",
                                    "denied_burst"
                                  ]
                                },
                                "member": {
                                  "type": "string",
                                  "description": "Sandbox id"
                                },
                                "member_name": {
                                  "type": [
                                    "string",
                                    "null"
                                  ]
                                },
                                "detail": {
                                  "type": "string"
                                },
                                "host": {
                                  "type": [
                                    "string",
                                    "null"
                                  ]
                                },
                                "first_seen": {
                                  "type": "integer",
                                  "description": "Unix ms"
                                }
                              }
                            }
                          },
                          "stats": {
                            "type": "object",
                            "properties": {
                              "read": {
                                "type": "boolean"
                              },
                              "note": {
                                "type": "string"
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      },
      "post": {
        "operationId": "createSwarm",
        "summary": "Checkpoint a sandbox and fork it into a named swarm under one egress policy",
        "tags": [
          "Swarms"
        ],
        "x-kosa8-scope": "sandboxes:write",
        "description": "Needs the `sandboxes:write` scope (or one that includes it). The checkpoint and the fork are the same calls as POST /v1/sandboxes/{id}/checkpoints and /fork, with the same payment, quota and fork limits. Members are labelled swarm, swarm.member and swarm.parent. If a member's egress policy cannot be applied, every member is deleted (502 egress_failed).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "pattern": "^[a-z0-9][a-z0-9-]{0,39}$"
                  },
                  "from_sandbox_id": {
                    "type": "string",
                    "description": "A running or sleeping sandbox"
                  },
                  "count": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 100
                  },
                  "egress": {
                    "type": "object",
                    "properties": {
                      "internet": {
                        "type": "boolean",
                        "description": "false: nothing leaves but what allow and presets name. Default true when nothing is listed"
                      },
                      "allow": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "description": "Hostnames (exact), *.domain wildcards (any depth below, not the domain), IPv4 addresses or CIDRs"
                      },
                      "deny": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "description": "Refused even where allow covers them. A name is refused at DNS; a CIDR for every packet"
                      },
                      "presets": {
                        "type": "array",
                        "items": {
                          "type": "string",
                          "enum": [
                            "common",
                            "npm",
                            "pypi",
                            "github",
                            "go",
                            "crates",
                            "rubygems",
                            "maven",
                            "apt",
                            "alpine",
                            "docker",
                            "huggingface",
                            "ai"
                          ]
                        }
                      }
                    },
                    "description": "The members' egress policy. Default: the parent's own, else the organization's"
                  }
                },
                "required": [
                  "name",
                  "from_sandbox_id",
                  "count"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "swarm": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "description": "swm_…"
                        },
                        "name": {
                          "type": "string"
                        },
                        "parent": {
                          "type": "string",
                          "description": "The sandbox the members were forked from"
                        },
                        "start_checkpoint": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The parent's checkpoint taken at creation"
                        },
                        "created_at": {
                          "type": "integer"
                        },
                        "created_by": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "killed_at": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "state": {
                          "type": "string",
                          "enum": [
                            "running",
                            "paused",
                            "killed",
                            "mixed"
                          ]
                        },
                        "policy": {
                          "type": [
                            "object",
                            "null"
                          ],
                          "properties": {
                            "internet": {
                              "type": "boolean"
                            },
                            "allow": {
                              "type": "array",
                              "items": {
                                "type": "string"
                              },
                              "description": "Hostnames (exact), *.domain wildcards (any depth below, not the domain), IPv4 addresses or CIDRs"
                            },
                            "deny": {
                              "type": "array",
                              "items": {
                                "type": "string"
                              },
                              "description": "Hostnames (exact), *.domain wildcards (any depth below, not the domain), IPv4 addresses or CIDRs"
                            },
                            "presets": {
                              "type": "array",
                              "items": {
                                "type": "string"
                              }
                            },
                            "source": {
                              "type": "string",
                              "enum": [
                                "sandbox",
                                "org",
                                "default"
                              ]
                            },
                            "enforced": {
                              "type": "string",
                              "description": "The policy the host enforces: any, deny, allow:…[;deny:…] or block:…"
                            }
                          }
                        },
                        "counts": {
                          "type": "object",
                          "properties": {
                            "members": {
                              "type": "integer"
                            },
                            "running": {
                              "type": "integer"
                            },
                            "paused": {
                              "type": "integer"
                            },
                            "gone": {
                              "type": "integer"
                            },
                            "anomalies": {
                              "type": "integer"
                            }
                          }
                        },
                        "members": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "name": {
                                "type": "string",
                                "description": "<swarm>-<n>"
                              },
                              "state": {
                                "type": "string",
                                "description": "The sandbox's state: running, sleeping, creating, deleted, …"
                              },
                              "egress": {
                                "type": "object",
                                "properties": {
                                  "allowed": {
                                    "type": [
                                      "integer",
                                      "null"
                                    ],
                                    "description": "Always null on kosa8 Cloud: the host does not report it"
                                  },
                                  "denied": {
                                    "type": [
                                      "integer",
                                      "null"
                                    ],
                                    "description": "Packets refused by egress since the member last booted; null when not read"
                                  },
                                  "bytes_out": {
                                    "type": [
                                      "integer",
                                      "null"
                                    ]
                                  },
                                  "hosts": {
                                    "type": "array",
                                    "items": {
                                      "type": "string"
                                    },
                                    "description": "Always empty on kosa8 Cloud"
                                  }
                                }
                              },
                              "anomalies": {
                                "type": "array",
                                "items": {
                                  "type": "object",
                                  "properties": {
                                    "kind": {
                                      "type": "string",
                                      "enum": [
                                        "rare_host",
                                        "egress_spike",
                                        "denied_burst"
                                      ]
                                    },
                                    "member": {
                                      "type": "string",
                                      "description": "Sandbox id"
                                    },
                                    "member_name": {
                                      "type": [
                                        "string",
                                        "null"
                                      ]
                                    },
                                    "detail": {
                                      "type": "string"
                                    },
                                    "host": {
                                      "type": [
                                        "string",
                                        "null"
                                      ]
                                    },
                                    "first_seen": {
                                      "type": "integer",
                                      "description": "Unix ms"
                                    }
                                  }
                                }
                              }
                            }
                          }
                        },
                        "anomalies": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "kind": {
                                "type": "string",
                                "enum": [
                                  "rare_host",
                                  "egress_spike",
                                  "denied_burst"
                                ]
                              },
                              "member": {
                                "type": "string",
                                "description": "Sandbox id"
                              },
                              "member_name": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "detail": {
                                "type": "string"
                              },
                              "host": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "first_seen": {
                                "type": "integer",
                                "description": "Unix ms"
                              }
                            }
                          }
                        },
                        "stats": {
                          "type": "object",
                          "properties": {
                            "read": {
                              "type": "boolean"
                            },
                            "note": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "402": {
            "$ref": "#/components/responses/E402"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          },
          "501": {
            "$ref": "#/components/responses/E501"
          },
          "502": {
            "$ref": "#/components/responses/E502"
          },
          "503": {
            "$ref": "#/components/responses/E503"
          }
        }
      }
    },
    "/v1/swarms/{id}": {
      "get": {
        "operationId": "getSwarm",
        "summary": "A swarm with each running member's egress counters and anomalies",
        "tags": [
          "Swarms"
        ],
        "x-kosa8-scope": "sandboxes:read",
        "description": "Needs the `sandboxes:read` scope (or one that includes it). ?stats=0 skips the counters. Counters come from the host: packets refused by egress and bytes out since the member last booted. Anomalies found (denied_burst: >= 20 refused; egress_spike: bytes out > 10x the median and > 1 MiB) are kept and written once to the audit log as swarm.anomaly. rare_host needs the hosts each member contacted, which kosa8 Cloud hosts do not report.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Swarm id (swm_…) or name"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "swarm": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "description": "swm_…"
                        },
                        "name": {
                          "type": "string"
                        },
                        "parent": {
                          "type": "string",
                          "description": "The sandbox the members were forked from"
                        },
                        "start_checkpoint": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The parent's checkpoint taken at creation"
                        },
                        "created_at": {
                          "type": "integer"
                        },
                        "created_by": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "killed_at": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "state": {
                          "type": "string",
                          "enum": [
                            "running",
                            "paused",
                            "killed",
                            "mixed"
                          ]
                        },
                        "policy": {
                          "type": [
                            "object",
                            "null"
                          ],
                          "properties": {
                            "internet": {
                              "type": "boolean"
                            },
                            "allow": {
                              "type": "array",
                              "items": {
                                "type": "string"
                              },
                              "description": "Hostnames (exact), *.domain wildcards (any depth below, not the domain), IPv4 addresses or CIDRs"
                            },
                            "deny": {
                              "type": "array",
                              "items": {
                                "type": "string"
                              },
                              "description": "Hostnames (exact), *.domain wildcards (any depth below, not the domain), IPv4 addresses or CIDRs"
                            },
                            "presets": {
                              "type": "array",
                              "items": {
                                "type": "string"
                              }
                            },
                            "source": {
                              "type": "string",
                              "enum": [
                                "sandbox",
                                "org",
                                "default"
                              ]
                            },
                            "enforced": {
                              "type": "string",
                              "description": "The policy the host enforces: any, deny, allow:…[;deny:…] or block:…"
                            }
                          }
                        },
                        "counts": {
                          "type": "object",
                          "properties": {
                            "members": {
                              "type": "integer"
                            },
                            "running": {
                              "type": "integer"
                            },
                            "paused": {
                              "type": "integer"
                            },
                            "gone": {
                              "type": "integer"
                            },
                            "anomalies": {
                              "type": "integer"
                            }
                          }
                        },
                        "members": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "name": {
                                "type": "string",
                                "description": "<swarm>-<n>"
                              },
                              "state": {
                                "type": "string",
                                "description": "The sandbox's state: running, sleeping, creating, deleted, …"
                              },
                              "egress": {
                                "type": "object",
                                "properties": {
                                  "allowed": {
                                    "type": [
                                      "integer",
                                      "null"
                                    ],
                                    "description": "Always null on kosa8 Cloud: the host does not report it"
                                  },
                                  "denied": {
                                    "type": [
                                      "integer",
                                      "null"
                                    ],
                                    "description": "Packets refused by egress since the member last booted; null when not read"
                                  },
                                  "bytes_out": {
                                    "type": [
                                      "integer",
                                      "null"
                                    ]
                                  },
                                  "hosts": {
                                    "type": "array",
                                    "items": {
                                      "type": "string"
                                    },
                                    "description": "Always empty on kosa8 Cloud"
                                  }
                                }
                              },
                              "anomalies": {
                                "type": "array",
                                "items": {
                                  "type": "object",
                                  "properties": {
                                    "kind": {
                                      "type": "string",
                                      "enum": [
                                        "rare_host",
                                        "egress_spike",
                                        "denied_burst"
                                      ]
                                    },
                                    "member": {
                                      "type": "string",
                                      "description": "Sandbox id"
                                    },
                                    "member_name": {
                                      "type": [
                                        "string",
                                        "null"
                                      ]
                                    },
                                    "detail": {
                                      "type": "string"
                                    },
                                    "host": {
                                      "type": [
                                        "string",
                                        "null"
                                      ]
                                    },
                                    "first_seen": {
                                      "type": "integer",
                                      "description": "Unix ms"
                                    }
                                  }
                                }
                              }
                            }
                          }
                        },
                        "anomalies": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "kind": {
                                "type": "string",
                                "enum": [
                                  "rare_host",
                                  "egress_spike",
                                  "denied_burst"
                                ]
                              },
                              "member": {
                                "type": "string",
                                "description": "Sandbox id"
                              },
                              "member_name": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "detail": {
                                "type": "string"
                              },
                              "host": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "first_seen": {
                                "type": "integer",
                                "description": "Unix ms"
                              }
                            }
                          }
                        },
                        "stats": {
                          "type": "object",
                          "properties": {
                            "read": {
                              "type": "boolean"
                            },
                            "note": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      }
    },
    "/v1/swarms/{id}/pause": {
      "post": {
        "operationId": "pauseSwarm",
        "summary": "Put every running member to sleep (state kept)",
        "tags": [
          "Swarms"
        ],
        "x-kosa8-scope": "sandboxes:write",
        "description": "Needs the `sandboxes:write` scope (or one that includes it).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Swarm id (swm_…) or name"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "swarm": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "description": "swm_…"
                        },
                        "name": {
                          "type": "string"
                        },
                        "parent": {
                          "type": "string",
                          "description": "The sandbox the members were forked from"
                        },
                        "start_checkpoint": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The parent's checkpoint taken at creation"
                        },
                        "created_at": {
                          "type": "integer"
                        },
                        "created_by": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "killed_at": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "state": {
                          "type": "string",
                          "enum": [
                            "running",
                            "paused",
                            "killed",
                            "mixed"
                          ]
                        },
                        "policy": {
                          "type": [
                            "object",
                            "null"
                          ],
                          "properties": {
                            "internet": {
                              "type": "boolean"
                            },
                            "allow": {
                              "type": "array",
                              "items": {
                                "type": "string"
                              },
                              "description": "Hostnames (exact), *.domain wildcards (any depth below, not the domain), IPv4 addresses or CIDRs"
                            },
                            "deny": {
                              "type": "array",
                              "items": {
                                "type": "string"
                              },
                              "description": "Hostnames (exact), *.domain wildcards (any depth below, not the domain), IPv4 addresses or CIDRs"
                            },
                            "presets": {
                              "type": "array",
                              "items": {
                                "type": "string"
                              }
                            },
                            "source": {
                              "type": "string",
                              "enum": [
                                "sandbox",
                                "org",
                                "default"
                              ]
                            },
                            "enforced": {
                              "type": "string",
                              "description": "The policy the host enforces: any, deny, allow:…[;deny:…] or block:…"
                            }
                          }
                        },
                        "counts": {
                          "type": "object",
                          "properties": {
                            "members": {
                              "type": "integer"
                            },
                            "running": {
                              "type": "integer"
                            },
                            "paused": {
                              "type": "integer"
                            },
                            "gone": {
                              "type": "integer"
                            },
                            "anomalies": {
                              "type": "integer"
                            }
                          }
                        },
                        "members": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "name": {
                                "type": "string",
                                "description": "<swarm>-<n>"
                              },
                              "state": {
                                "type": "string",
                                "description": "The sandbox's state: running, sleeping, creating, deleted, …"
                              },
                              "egress": {
                                "type": "object",
                                "properties": {
                                  "allowed": {
                                    "type": [
                                      "integer",
                                      "null"
                                    ],
                                    "description": "Always null on kosa8 Cloud: the host does not report it"
                                  },
                                  "denied": {
                                    "type": [
                                      "integer",
                                      "null"
                                    ],
                                    "description": "Packets refused by egress since the member last booted; null when not read"
                                  },
                                  "bytes_out": {
                                    "type": [
                                      "integer",
                                      "null"
                                    ]
                                  },
                                  "hosts": {
                                    "type": "array",
                                    "items": {
                                      "type": "string"
                                    },
                                    "description": "Always empty on kosa8 Cloud"
                                  }
                                }
                              },
                              "anomalies": {
                                "type": "array",
                                "items": {
                                  "type": "object",
                                  "properties": {
                                    "kind": {
                                      "type": "string",
                                      "enum": [
                                        "rare_host",
                                        "egress_spike",
                                        "denied_burst"
                                      ]
                                    },
                                    "member": {
                                      "type": "string",
                                      "description": "Sandbox id"
                                    },
                                    "member_name": {
                                      "type": [
                                        "string",
                                        "null"
                                      ]
                                    },
                                    "detail": {
                                      "type": "string"
                                    },
                                    "host": {
                                      "type": [
                                        "string",
                                        "null"
                                      ]
                                    },
                                    "first_seen": {
                                      "type": "integer",
                                      "description": "Unix ms"
                                    }
                                  }
                                }
                              }
                            }
                          }
                        },
                        "anomalies": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "kind": {
                                "type": "string",
                                "enum": [
                                  "rare_host",
                                  "egress_spike",
                                  "denied_burst"
                                ]
                              },
                              "member": {
                                "type": "string",
                                "description": "Sandbox id"
                              },
                              "member_name": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "detail": {
                                "type": "string"
                              },
                              "host": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "first_seen": {
                                "type": "integer",
                                "description": "Unix ms"
                              }
                            }
                          }
                        },
                        "stats": {
                          "type": "object",
                          "properties": {
                            "read": {
                              "type": "boolean"
                            },
                            "note": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    },
                    "done": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "Members changed"
                    },
                    "failed": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "status": {
                            "type": "integer"
                          },
                          "error": {
                            "type": [
                              "string",
                              "null"
                            ]
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      }
    },
    "/v1/swarms/{id}/resume": {
      "post": {
        "operationId": "resumeSwarm",
        "summary": "Wake every sleeping member",
        "tags": [
          "Swarms"
        ],
        "x-kosa8-scope": "sandboxes:write",
        "description": "Needs the `sandboxes:write` scope (or one that includes it).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Swarm id (swm_…) or name"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "swarm": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "description": "swm_…"
                        },
                        "name": {
                          "type": "string"
                        },
                        "parent": {
                          "type": "string",
                          "description": "The sandbox the members were forked from"
                        },
                        "start_checkpoint": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The parent's checkpoint taken at creation"
                        },
                        "created_at": {
                          "type": "integer"
                        },
                        "created_by": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "killed_at": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "state": {
                          "type": "string",
                          "enum": [
                            "running",
                            "paused",
                            "killed",
                            "mixed"
                          ]
                        },
                        "policy": {
                          "type": [
                            "object",
                            "null"
                          ],
                          "properties": {
                            "internet": {
                              "type": "boolean"
                            },
                            "allow": {
                              "type": "array",
                              "items": {
                                "type": "string"
                              },
                              "description": "Hostnames (exact), *.domain wildcards (any depth below, not the domain), IPv4 addresses or CIDRs"
                            },
                            "deny": {
                              "type": "array",
                              "items": {
                                "type": "string"
                              },
                              "description": "Hostnames (exact), *.domain wildcards (any depth below, not the domain), IPv4 addresses or CIDRs"
                            },
                            "presets": {
                              "type": "array",
                              "items": {
                                "type": "string"
                              }
                            },
                            "source": {
                              "type": "string",
                              "enum": [
                                "sandbox",
                                "org",
                                "default"
                              ]
                            },
                            "enforced": {
                              "type": "string",
                              "description": "The policy the host enforces: any, deny, allow:…[;deny:…] or block:…"
                            }
                          }
                        },
                        "counts": {
                          "type": "object",
                          "properties": {
                            "members": {
                              "type": "integer"
                            },
                            "running": {
                              "type": "integer"
                            },
                            "paused": {
                              "type": "integer"
                            },
                            "gone": {
                              "type": "integer"
                            },
                            "anomalies": {
                              "type": "integer"
                            }
                          }
                        },
                        "members": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "name": {
                                "type": "string",
                                "description": "<swarm>-<n>"
                              },
                              "state": {
                                "type": "string",
                                "description": "The sandbox's state: running, sleeping, creating, deleted, …"
                              },
                              "egress": {
                                "type": "object",
                                "properties": {
                                  "allowed": {
                                    "type": [
                                      "integer",
                                      "null"
                                    ],
                                    "description": "Always null on kosa8 Cloud: the host does not report it"
                                  },
                                  "denied": {
                                    "type": [
                                      "integer",
                                      "null"
                                    ],
                                    "description": "Packets refused by egress since the member last booted; null when not read"
                                  },
                                  "bytes_out": {
                                    "type": [
                                      "integer",
                                      "null"
                                    ]
                                  },
                                  "hosts": {
                                    "type": "array",
                                    "items": {
                                      "type": "string"
                                    },
                                    "description": "Always empty on kosa8 Cloud"
                                  }
                                }
                              },
                              "anomalies": {
                                "type": "array",
                                "items": {
                                  "type": "object",
                                  "properties": {
                                    "kind": {
                                      "type": "string",
                                      "enum": [
                                        "rare_host",
                                        "egress_spike",
                                        "denied_burst"
                                      ]
                                    },
                                    "member": {
                                      "type": "string",
                                      "description": "Sandbox id"
                                    },
                                    "member_name": {
                                      "type": [
                                        "string",
                                        "null"
                                      ]
                                    },
                                    "detail": {
                                      "type": "string"
                                    },
                                    "host": {
                                      "type": [
                                        "string",
                                        "null"
                                      ]
                                    },
                                    "first_seen": {
                                      "type": "integer",
                                      "description": "Unix ms"
                                    }
                                  }
                                }
                              }
                            }
                          }
                        },
                        "anomalies": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "kind": {
                                "type": "string",
                                "enum": [
                                  "rare_host",
                                  "egress_spike",
                                  "denied_burst"
                                ]
                              },
                              "member": {
                                "type": "string",
                                "description": "Sandbox id"
                              },
                              "member_name": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "detail": {
                                "type": "string"
                              },
                              "host": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "first_seen": {
                                "type": "integer",
                                "description": "Unix ms"
                              }
                            }
                          }
                        },
                        "stats": {
                          "type": "object",
                          "properties": {
                            "read": {
                              "type": "boolean"
                            },
                            "note": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    },
                    "done": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "Members changed"
                    },
                    "failed": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "status": {
                            "type": "integer"
                          },
                          "error": {
                            "type": [
                              "string",
                              "null"
                            ]
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          }
        }
      }
    },
    "/v1/swarms/{id}/kill": {
      "post": {
        "operationId": "killSwarm",
        "summary": "The kill switch: every running member to sleep and the swarm marked killed",
        "tags": [
          "Swarms"
        ],
        "x-kosa8-scope": "sandboxes:write",
        "description": "Needs the `sandboxes:write` scope (or one that includes it). Works while the organization is frozen. A killed swarm's name can be used again.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Swarm id (swm_…) or name"
          },
          {
            "name": "rm",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ]
            },
            "description": "1: delete every member instead"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "swarm": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "description": "swm_…"
                        },
                        "name": {
                          "type": "string"
                        },
                        "parent": {
                          "type": "string",
                          "description": "The sandbox the members were forked from"
                        },
                        "start_checkpoint": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The parent's checkpoint taken at creation"
                        },
                        "created_at": {
                          "type": "integer"
                        },
                        "created_by": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "killed_at": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "state": {
                          "type": "string",
                          "enum": [
                            "running",
                            "paused",
                            "killed",
                            "mixed"
                          ]
                        },
                        "policy": {
                          "type": [
                            "object",
                            "null"
                          ],
                          "properties": {
                            "internet": {
                              "type": "boolean"
                            },
                            "allow": {
                              "type": "array",
                              "items": {
                                "type": "string"
                              },
                              "description": "Hostnames (exact), *.domain wildcards (any depth below, not the domain), IPv4 addresses or CIDRs"
                            },
                            "deny": {
                              "type": "array",
                              "items": {
                                "type": "string"
                              },
                              "description": "Hostnames (exact), *.domain wildcards (any depth below, not the domain), IPv4 addresses or CIDRs"
                            },
                            "presets": {
                              "type": "array",
                              "items": {
                                "type": "string"
                              }
                            },
                            "source": {
                              "type": "string",
                              "enum": [
                                "sandbox",
                                "org",
                                "default"
                              ]
                            },
                            "enforced": {
                              "type": "string",
                              "description": "The policy the host enforces: any, deny, allow:…[;deny:…] or block:…"
                            }
                          }
                        },
                        "counts": {
                          "type": "object",
                          "properties": {
                            "members": {
                              "type": "integer"
                            },
                            "running": {
                              "type": "integer"
                            },
                            "paused": {
                              "type": "integer"
                            },
                            "gone": {
                              "type": "integer"
                            },
                            "anomalies": {
                              "type": "integer"
                            }
                          }
                        },
                        "members": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "name": {
                                "type": "string",
                                "description": "<swarm>-<n>"
                              },
                              "state": {
                                "type": "string",
                                "description": "The sandbox's state: running, sleeping, creating, deleted, …"
                              },
                              "egress": {
                                "type": "object",
                                "properties": {
                                  "allowed": {
                                    "type": [
                                      "integer",
                                      "null"
                                    ],
                                    "description": "Always null on kosa8 Cloud: the host does not report it"
                                  },
                                  "denied": {
                                    "type": [
                                      "integer",
                                      "null"
                                    ],
                                    "description": "Packets refused by egress since the member last booted; null when not read"
                                  },
                                  "bytes_out": {
                                    "type": [
                                      "integer",
                                      "null"
                                    ]
                                  },
                                  "hosts": {
                                    "type": "array",
                                    "items": {
                                      "type": "string"
                                    },
                                    "description": "Always empty on kosa8 Cloud"
                                  }
                                }
                              },
                              "anomalies": {
                                "type": "array",
                                "items": {
                                  "type": "object",
                                  "properties": {
                                    "kind": {
                                      "type": "string",
                                      "enum": [
                                        "rare_host",
                                        "egress_spike",
                                        "denied_burst"
                                      ]
                                    },
                                    "member": {
                                      "type": "string",
                                      "description": "Sandbox id"
                                    },
                                    "member_name": {
                                      "type": [
                                        "string",
                                        "null"
                                      ]
                                    },
                                    "detail": {
                                      "type": "string"
                                    },
                                    "host": {
                                      "type": [
                                        "string",
                                        "null"
                                      ]
                                    },
                                    "first_seen": {
                                      "type": "integer",
                                      "description": "Unix ms"
                                    }
                                  }
                                }
                              }
                            }
                          }
                        },
                        "anomalies": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "kind": {
                                "type": "string",
                                "enum": [
                                  "rare_host",
                                  "egress_spike",
                                  "denied_burst"
                                ]
                              },
                              "member": {
                                "type": "string",
                                "description": "Sandbox id"
                              },
                              "member_name": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "detail": {
                                "type": "string"
                              },
                              "host": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "first_seen": {
                                "type": "integer",
                                "description": "Unix ms"
                              }
                            }
                          }
                        },
                        "stats": {
                          "type": "object",
                          "properties": {
                            "read": {
                              "type": "boolean"
                            },
                            "note": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    },
                    "done": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "Members changed"
                    },
                    "failed": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "status": {
                            "type": "integer"
                          },
                          "error": {
                            "type": [
                              "string",
                              "null"
                            ]
                          }
                        }
                      }
                    },
                    "removed": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "k8c_live_…",
        "description": "A kosa8 Cloud API key"
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "description": "Stable machine code, e.g. plan_required, plan_limit, plan_feature, payment_required, spending_cap_reached, quota_exceeded, no_capacity, not_found"
          },
          "limit_name": {
            "type": "string",
            "description": "402 plan_limit: sandbox_hours, running, size, persistent or snapshots"
          },
          "limit": {
            "type": "number",
            "description": "402 plan_limit: the plan's limit"
          },
          "used": {
            "type": "number",
            "description": "402 plan_limit: what the organization has used (for size, the vCPU asked for)"
          },
          "plan": {
            "type": "string",
            "description": "402 plan_limit and plan_feature: the organization's plan"
          },
          "next_plan": {
            "type": [
              "string",
              "null"
            ],
            "description": "402 plan_limit and plan_feature: the first plan that includes more, or null (contact sales)"
          },
          "feature": {
            "type": "string",
            "description": "402 plan_feature: the feature the plan lacks"
          },
          "options": {
            "type": "array",
            "description": "402 plan_limit: the ways past the limit, cheaper a month first: an add-on pack (kind pack, addon) and the next plan (kind upgrade, plan; monthly_usd is the difference for the org's people). Offer them in this order",
            "items": {
              "type": "object",
              "properties": {
                "kind": {
                  "type": "string",
                  "enum": [
                    "pack",
                    "upgrade"
                  ]
                },
                "addon": {
                  "type": "string"
                },
                "plan": {
                  "type": "string"
                },
                "label": {
                  "type": "string"
                },
                "monthly_usd": {
                  "type": "number"
                },
                "url": {
                  "type": "string",
                  "format": "uri"
                }
              }
            }
          },
          "pack_url": {
            "type": "string",
            "format": "uri",
            "description": "402 plan_limit: where to add the pack for this limit, when one is sold"
          },
          "retryable": {
            "type": "boolean",
            "description": "503 no_capacity: true; retry after retry_after_s (also the Retry-After header). Not a plan limit"
          },
          "message": {
            "type": "string",
            "description": "A sentence a person can act on"
          },
          "upgrade_url": {
            "type": "string",
            "format": "uri",
            "description": "402: where the person adds a payment method or credit, or raises the cap"
          },
          "agent_message": {
            "type": "string",
            "description": "402 and 429 quota_exceeded: a sentence an AI agent should relay to its person word for word"
          },
          "request_url": {
            "type": "string",
            "format": "uri",
            "description": "429 quota_exceeded: where to ask for a higher limit (POST /v1/limits/request)"
          }
        },
        "required": [
          "error",
          "message"
        ]
      },
      "Moment": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "enum": [
              "add_card",
              "credit_runway",
              "spending_cap",
              "concurrency",
              "team",
              "yearly",
              "security_review",
              "plan_fit",
              "referral"
            ]
          },
          "kind": {
            "type": "string",
            "description": "card, credit, cap, limit, plan, billing, contact or referral"
          },
          "title": {
            "type": "string"
          },
          "body": {
            "type": "string",
            "description": "Every figure in it is the org's own data or a list price"
          },
          "cta": {
            "type": "object",
            "properties": {
              "label": {
                "type": "string"
              },
              "action": {
                "type": "string",
                "enum": [
                  "checkout",
                  "pack",
                  "portal",
                  "settings"
                ],
                "description": "checkout: POST /v1/billing/checkout with plan (if any); pack: the same with pack; portal: POST /v1/billing/portal; settings: the spending cap"
              },
              "href": {
                "type": "string",
                "description": "Instead of action: a mailto: address or a dashboard page (#refer)"
              },
              "plan": {
                "type": "string"
              },
              "pack": {
                "type": "string",
                "description": "The credit pack's product_id"
              }
            },
            "required": [
              "label"
            ]
          },
          "plan": {
            "type": "string"
          },
          "saving_usd": {
            "type": "number",
            "description": "Present only when the saving is real"
          },
          "projected_at": {
            "type": "integer",
            "description": "When credit runs out at the current pace (ms)"
          },
          "reason": {
            "type": "object",
            "properties": {
              "metric": {
                "type": "string"
              },
              "value": {
                "type": "number"
              },
              "threshold": {
                "type": "number"
              }
            },
            "required": [
              "metric",
              "value",
              "threshold"
            ]
          }
        },
        "required": [
          "id",
          "kind",
          "title",
          "body",
          "cta",
          "reason"
        ]
      },
      "Sandbox": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "examples": [
              "sbx_4Qm2…"
            ]
          },
          "state": {
            "type": "string",
            "enum": [
              "creating",
              "running",
              "paused",
              "sleeping",
              "stopped",
              "expired",
              "error",
              "deleted",
              "host_removed",
              "host_lost"
            ],
            "description": "expired: past its delete_after; it takes no more work and is deleted within about a minute"
          },
          "template": {
            "type": "string"
          },
          "origin_item_version": {
            "type": [
              "string",
              "null"
            ],
            "description": "The kosa8 Store version it was started (or forked) from"
          },
          "cpus": {
            "type": "number"
          },
          "mem_mb": {
            "type": "integer"
          },
          "source": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "pool",
              "restore",
              "cold",
              "fork",
              "snapshot",
              null
            ]
          },
          "snapshot_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "The snapshot it was made from (POST /v1/sandboxes {snapshot}), if any"
          },
          "parent_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "The sandbox it was forked from, if any"
          },
          "region": {
            "type": [
              "string",
              "null"
            ]
          },
          "own_host": {
            "type": "boolean"
          },
          "created_at": {
            "type": "integer",
            "description": "Unix ms"
          },
          "started_at": {
            "type": [
              "integer",
              "null"
            ]
          },
          "stopped_at": {
            "type": [
              "integer",
              "null"
            ]
          },
          "deleted_at": {
            "type": [
              "integer",
              "null"
            ]
          },
          "delete_after": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Unix ms: deleted automatically then"
          },
          "sleep_after_s": {
            "type": [
              "integer",
              "null"
            ]
          },
          "last_error": {
            "type": [
              "string",
              "null"
            ]
          },
          "host_unreachable": {
            "type": "boolean"
          },
          "running_s": {
            "type": "integer"
          },
          "asleep_s": {
            "type": "integer"
          },
          "cost_usd": {
            "type": "number",
            "description": "Estimate so far"
          },
          "persistent": {
            "type": "boolean",
            "description": "Every exec runs in one long-lived container: the whole filesystem and background processes last between commands"
          },
          "name": {
            "type": [
              "string",
              "null"
            ],
            "description": "The label given at create"
          },
          "image": {
            "type": [
              "string",
              "null"
            ],
            "description": "A sized sandbox's own image; null for a template's"
          },
          "disk_gb": {
            "type": [
              "integer",
              "null"
            ],
            "description": "A sized sandbox's data disk (holds / and /workspace); null for a template's (32 GB)"
          },
          "cpu": {
            "type": "string",
            "enum": [
              "shared",
              "dedicated"
            ],
            "description": "dedicated: every vCPU is a whole physical core of its own"
          }
        },
        "required": [
          "id",
          "state",
          "template"
        ]
      },
      "SandboxCreate": {
        "type": "object",
        "properties": {
          "template": {
            "type": "string",
            "description": "Template key from GET /v1/templates (default the org's default, base), or a kosa8 Store item: creator/name or creator/name@1.2.3"
          },
          "accept_price": {
            "type": "number",
            "description": "A paid Store item only: its current price in USD, which the person agreed to. Missing: 402 price_not_accepted; different: 409 price_changed (both carry the price)"
          },
          "region": {
            "type": "string",
            "description": "us-ash1 (Dallas, US) or eu-hel1 (Helsinki, EU), or the area alone (us, eu). Default: the org's default_region, else the region nearest the caller"
          },
          "sleep_after_s": {
            "type": "integer",
            "minimum": 0,
            "maximum": 604800,
            "description": "Idle seconds before it sleeps; 0 never; default 300"
          },
          "ttl_s": {
            "type": "integer",
            "minimum": 60,
            "maximum": 7776000,
            "description": "Delete it this many seconds from now"
          },
          "delete_after": {
            "type": [
              "integer",
              "string"
            ],
            "description": "Or: delete it at this time, Unix ms or ISO 8601 (60 s to 90 days from now)"
          },
          "persistent": {
            "type": "boolean",
            "description": "Run every exec, streamed or not, in one long-lived container: packages, $HOME, /var/lib and anything outside /workspace persist, and a process started with `nohup cmd &` keeps running after the exec returns, until the sandbox is deleted (it also keeps the sandbox from sleeping). Default false: each command runs in a fresh container that shares only /workspace. An exec then takes no image"
          },
          "docker": {
            "type": "boolean",
            "description": "Let the sandbox run its own Docker engine: start it with `dockerd > /var/log/dockerd.log 2>&1 &`, then `docker run`, `docker build` and compose work, pulling over the sandbox's egress. Needs a size or image (a sized create) and makes the sandbox persistent. The container gets the privileges dockerd needs inside the sandbox's own microVM, which stays the isolation boundary"
          },
          "size": {
            "type": "string",
            "enum": [
              "2x4",
              "4x8",
              "8x16",
              "16x32"
            ],
            "description": "vCPU x GiB. With size, cpus+mem_mb, image or disk_gb the sandbox is booted cold at that size (202, state creating, until it is up; poll GET). When a template's pool already holds VMs of exactly that size and image with the default disk (base-2x4 is base, alpine, at 2x4) and nothing is set at boot (no docker, dedicated cpu, egress or secrets), the create takes a started VM from that pool instead and answers 201 running, its template that pool's (e.g. base-2x4). Needs a payment method"
          },
          "cpus": {
            "type": "integer",
            "description": "Or: cpus and mem_mb of one of the sizes (4 and 8192 for 4x8)"
          },
          "mem_mb": {
            "type": "integer"
          },
          "image": {
            "type": "string",
            "description": "An OCI image to run, e.g. ghcr.io/starslingdev/sandbox-benchmarks-toolchain:v8 (default size 2x4)"
          },
          "disk_gb": {
            "type": "integer",
            "minimum": 8,
            "maximum": 200,
            "description": "The data disk, which holds / and /workspace; default 32"
          },
          "name": {
            "type": "string",
            "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$",
            "description": "Your label for it; GET /v1/sandboxes?name= finds it"
          },
          "cpu": {
            "type": "string",
            "enum": [
              "shared",
              "dedicated"
            ],
            "description": "dedicated (with a size): each vCPU is a whole physical core of its own, its SMT sibling idle, RAM on hugepages; never sleeps, cannot be checkpointed or forked. 503 no_capacity when no host has the free cores. Default shared"
          },
          "env": {
            "type": "object",
            "maxProperties": 64,
            "additionalProperties": {
              "type": "string",
              "maxLength": 8192
            },
            "examples": [
              {
                "GREETING": "hello",
                "NODE_ENV": "production"
              }
            ],
            "description": "Environment variables for the sandbox: every command it runs gets them (through /exec, a direct exec_url, streamed or not, background or not, in a persistent container or a fresh one), the exec's own env winning per name. Kept with the sandbox on its host and carried to forks and to sandboxes made from its snapshots. Names: letters, digits and _, not starting with a digit. At most 64, each value at most 8 KiB, 64 KiB in all. Values are never logged or returned; the audit log holds names only"
          },
          "snapshot": {
            "type": "string",
            "pattern": "^snap_[A-Za-z0-9]{8,40}$",
            "description": "Make the sandbox from a snapshot of the org's (POST /v1/sandboxes/{id}/snapshots): it starts as the source was when the snapshot was taken, files, packages and running processes included, on the host that keeps the snapshot. Its template, size, image and disk are the snapshot's: give no template, size, cpus, mem_mb, image, disk_gb, docker, persistent, cpu or region. env (yours over the source's), name, ttl_s / delete_after and sleep_after_s are its own. Answers 201 running"
          }
        }
      },
      "Exec": {
        "type": "object",
        "properties": {
          "cmd": {
            "type": "array",
            "items": {
              "type": "string",
              "maxLength": 8192
            },
            "minItems": 1,
            "maxItems": 256,
            "examples": [
              [
                "sh",
                "-c",
                "echo hi"
              ]
            ]
          },
          "image": {
            "type": "string",
            "description": "Run in this image instead of the template's"
          },
          "env": {
            "type": "array",
            "items": {
              "type": "string",
              "pattern": "^[A-Za-z_][A-Za-z0-9_]*="
            },
            "maxItems": 128,
            "description": "NAME=value"
          },
          "stream": {
            "type": "boolean",
            "description": "Answer as NDJSON (application/x-ndjson) while the command prints: {stream: stdout|stderr, data: base64} frames, then {done: true, exit} or {done: true, error}. While the command prints nothing, an empty stdout frame with heartbeat: true comes every 15 s; ignore it. Not held to the 90 s limit of a buffered exec. 501 not_available on a host without the data plane"
          },
          "background": {
            "type": "boolean",
            "description": "Detached: start the command and answer 202 {exec: {id, pid, state: running, output_path, exit_path}} at once. The command keeps running after the call returns, in the sandbox's own long-lived container (persistent or not), so files it writes anywhere (/tmp, /workspace, …) are there for later commands. Its stdout and stderr go to output_path (/workspace/.kosa8-bg/<id>.out) and its exit code to exit_path once it exits; GET /v1/sandboxes/{id}/exec/{exec_id} reports state, exit and output. Not with stream or another image. 501 not_available on a host without it"
          },
          "timeout_s": {
            "type": "integer",
            "minimum": 1,
            "maximum": 86400,
            "description": "Stop the command after this many seconds: 504 exec_timeout (with limit_s and the output so far) when buffered, at most 90 there; a last frame {done: true, error, code: exec_timeout} when streamed; with background, the host ends it then and GET …/exec/{exec_id} says timed_out (501 not_available on a host without it)"
          }
        },
        "required": [
          "cmd"
        ]
      },
      "BackgroundExec": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "examples": [
              "bg_3f9c0a1b2c3d4e5f"
            ]
          },
          "sandbox_id": {
            "type": "string"
          },
          "state": {
            "type": "string",
            "enum": [
              "running",
              "exited"
            ]
          },
          "pid": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Its process id in the sandbox's container (on start)"
          },
          "exit": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Its exit code, once exited"
          },
          "output_path": {
            "type": "string",
            "description": "Its stdout and stderr, as it prints: a workspace file the files API reads too"
          },
          "exit_path": {
            "type": "string"
          },
          "output": {
            "type": [
              "string",
              "null"
            ],
            "description": "GET only: its output so far (null past 1 MiB: read output_path with GET …/files/raw)"
          },
          "output_bytes": {
            "type": [
              "integer",
              "null"
            ]
          },
          "output_truncated": {
            "type": "boolean"
          },
          "timeout_s": {
            "type": "integer",
            "description": "The timeout_s it was started with"
          },
          "timed_out": {
            "type": "boolean",
            "description": "GET only: it ran past timeout_s and was ended"
          },
          "stopped": {
            "type": "boolean",
            "description": "GET only: POST …/stop ended it"
          }
        },
        "required": [
          "id",
          "state"
        ]
      },
      "Snapshot": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "examples": [
              "snap_9KkV…"
            ]
          },
          "name": {
            "type": [
              "string",
              "null"
            ]
          },
          "state": {
            "type": "string",
            "enum": [
              "creating",
              "ready",
              "error",
              "deleted"
            ],
            "description": "error: its host no longer has it (last_error); it is not billed from then"
          },
          "source_sandbox_id": {
            "type": "string",
            "description": "The sandbox it was taken from; deleting that sandbox does not delete the snapshot"
          },
          "template": {
            "type": "string"
          },
          "cpus": {
            "type": "integer"
          },
          "mem_mb": {
            "type": "integer"
          },
          "image": {
            "type": [
              "string",
              "null"
            ]
          },
          "disk_gb": {
            "type": [
              "integer",
              "null"
            ]
          },
          "persistent": {
            "type": "boolean"
          },
          "bytes": {
            "type": "integer",
            "description": "What it takes on disk, billed at storage_gb_month"
          },
          "region": {
            "type": [
              "string",
              "null"
            ],
            "description": "Its host's region: sandboxes made from it run there"
          },
          "created_at": {
            "type": "integer"
          },
          "deleted_at": {
            "type": [
              "integer",
              "null"
            ]
          },
          "last_error": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "id",
          "state",
          "source_sandbox_id"
        ]
      },
      "FileInfo": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "path": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "examples": [
              "file",
              "dir"
            ]
          },
          "size": {
            "type": "integer"
          },
          "mode": {
            "type": "integer",
            "description": "Unix permission bits as a number, e.g. 420 for 0644"
          },
          "mod_time": {
            "type": "string"
          }
        },
        "required": [
          "path"
        ]
      },
      "Checkpoint": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "auto": {
            "type": "boolean",
            "description": "Saved automatically before a rewind"
          },
          "created_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "bytes": {
            "type": "integer"
          }
        },
        "required": [
          "id"
        ]
      },
      "ExecResult": {
        "type": "object",
        "properties": {
          "exit": {
            "type": [
              "integer",
              "null"
            ]
          },
          "stdout": {
            "type": "string"
          },
          "stderr": {
            "type": "string"
          },
          "stdout_truncated": {
            "type": "boolean",
            "description": "A buffered exec keeps the first and the last 1 MiB of each stream; true when stdout was longer and its middle was dropped (a line \"[k8agent: N bytes of output dropped]\" marks where). Send stream: true for all of it, or write it to a file"
          },
          "stderr_truncated": {
            "type": "boolean",
            "description": "As stdout_truncated, for stderr"
          },
          "stdout_bytes": {
            "type": "integer",
            "description": "How many bytes the command wrote to stdout, kept or not"
          },
          "stderr_bytes": {
            "type": "integer",
            "description": "How many bytes the command wrote to stderr, kept or not"
          },
          "woke_ms": {
            "type": "integer",
            "description": "Present when the command woke a sleeping sandbox"
          }
        },
        "required": [
          "exit",
          "stdout",
          "stderr"
        ]
      },
      "DirectExec": {
        "type": "object",
        "properties": {
          "exec_url": {
            "type": "string",
            "description": "The host's exec endpoint for this sandbox"
          },
          "files_url": {
            "type": "string",
            "description": "The host's file endpoint for this sandbox (GET or PUT ?path=, with Range, offset= and append= as …/files/raw), taking the same token: big transfers go to the host straight, past the API's 100 MB request limit. Present when the host supports it"
          },
          "token": {
            "type": "string",
            "description": "Bearer token for exec_url (and files_url): this sandbox only"
          },
          "expires_at": {
            "type": "integer",
            "description": "When the token stops working, ms since the epoch"
          }
        },
        "required": [
          "exec_url",
          "token",
          "expires_at"
        ]
      },
      "Template": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string"
          },
          "cpus": {
            "type": "number"
          },
          "mem_mb": {
            "type": "integer"
          },
          "image": {
            "type": [
              "string",
              "null"
            ],
            "description": "null for a template with no image of its own"
          },
          "regions": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "hosts": {
            "type": "integer"
          },
          "warm": {
            "type": "integer"
          },
          "own_host": {
            "type": "boolean"
          }
        }
      },
      "ApiKey": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "prefix": {
            "type": "string"
          },
          "scopes": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "sandboxes:read",
                "sandboxes:write",
                "functions:invoke",
                "functions:deploy",
                "keys:manage",
                "audit:read",
                "admin"
              ]
            }
          },
          "created_at": {
            "type": "integer"
          },
          "last_used_at": {
            "type": [
              "integer",
              "null"
            ]
          },
          "revoked_at": {
            "type": [
              "integer",
              "null"
            ]
          },
          "expires_at": {
            "type": [
              "integer",
              "null"
            ]
          },
          "secret": {
            "type": "string",
            "description": "Only in the answer that made it"
          },
          "member_email": {
            "type": [
              "string",
              "null"
            ],
            "description": "The member the key belongs to; it ends with their membership. null: the organization's own key"
          },
          "created_by": {
            "type": [
              "string",
              "null"
            ],
            "description": "The member who made or last rotated it. The key never has more than that member's role allows, and is revoked when they are removed"
          }
        }
      },
      "Webhook": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "events": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "sandbox.created",
                "sandbox.deleted",
                "sandbox.slept",
                "sandbox.woke",
                "sandbox.error",
                "sandbox.killed",
                "sandbox.oom",
                "function.deployed",
                "function.invocation.failed",
                "spending_cap.reached",
                "plan.purchased",
                "plan.changed",
                "plan.canceled",
                "plan.renewed",
                "plan.payment_failed",
                "seats.changed",
                "plan_required.blocked",
                "plan_limit.near",
                "plan_limit.reached",
                "plan_feature.blocked",
                "hours.reset",
                "capacity.unavailable",
                "legacy_access.ending",
                "legacy_access.ended",
                "addon.purchased",
                "addon.canceled",
                "agent.tool_call.blocked",
                "agent.tool_call.decided"
              ]
            }
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "secret": {
            "type": "string",
            "description": "whsec_…, only in the answer that made it"
          }
        }
      },
      "DeviceStart": {
        "type": "object",
        "properties": {
          "device_code": {
            "type": "string",
            "description": "Secret: the device keeps it and polls with it"
          },
          "user_code": {
            "type": "string",
            "examples": [
              "BCDF-GH23"
            ]
          },
          "verification_uri": {
            "type": "string",
            "format": "uri"
          },
          "verification_uri_complete": {
            "type": "string",
            "format": "uri"
          },
          "interval": {
            "type": "integer",
            "description": "Seconds between polls"
          },
          "expires_in": {
            "type": "integer",
            "description": "Seconds"
          }
        },
        "required": [
          "device_code",
          "user_code",
          "verification_uri",
          "verification_uri_complete",
          "interval",
          "expires_in"
        ]
      },
      "Usage": {
        "type": "object",
        "properties": {
          "month": {
            "type": "object",
            "properties": {
              "gross_usd": {
                "type": "number"
              },
              "net_usd": {
                "type": "number"
              },
              "cost_usd": {
                "type": "number"
              }
            }
          },
          "spending_cap_usd": {
            "type": [
              "number",
              "null"
            ],
            "description": "Optional; null (the default) is no cap"
          },
          "plan_required": {
            "type": "boolean",
            "description": "True when new work is refused for want of a plan (402 plan_required)"
          },
          "plan_required_from": {
            "type": "string",
            "description": "The day accounts made before plans were required need one (2026-12-01)"
          },
          "plan_url": {
            "type": "string",
            "format": "uri",
            "description": "Where the person picks or changes a plan"
          },
          "plan_usage": {
            "type": [
              "object",
              "null"
            ],
            "description": "The plan's limits and what is used against each; null with no plan, on a contract or billing-exempt. applies is false before the limits start (applies_from); nudge is any meter at 80% or more",
            "properties": {
              "plan": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "people": {
                "type": "integer"
              },
              "applies": {
                "type": "boolean"
              },
              "applies_from": {
                "type": "string"
              },
              "sandbox_hours": {
                "type": "object",
                "properties": {
                  "used": {
                    "type": "number"
                  },
                  "limit": {
                    "type": "number"
                  }
                }
              },
              "running": {
                "type": "object",
                "properties": {
                  "used": {
                    "type": "integer"
                  },
                  "limit": {
                    "type": "integer"
                  }
                }
              },
              "persistent": {
                "type": "object",
                "properties": {
                  "used": {
                    "type": "integer"
                  },
                  "limit": {
                    "type": "integer"
                  }
                }
              },
              "snapshots": {
                "type": "object",
                "properties": {
                  "used": {
                    "type": "integer"
                  },
                  "limit": {
                    "type": "integer"
                  }
                }
              },
              "max_vcpus": {
                "type": "integer"
              },
              "max_mem_mb": {
                "type": "integer"
              },
              "features": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "next_plan": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "nudge": {
                "type": "boolean"
              },
              "nudge_limit": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "addons": {
                "type": "object",
                "description": "Add-on packs in force, {addon: quantity}; the limits above include them",
                "additionalProperties": {
                  "type": "integer"
                }
              },
              "options": {
                "type": "array",
                "description": "For the nudged limit: an add-on pack and the next plan, cheaper first (as in a 402 plan_limit)",
                "items": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "spending_cap": {
            "type": [
              "object",
              "null"
            ],
            "description": "The month against the cap: near from 80%, reached at 100% (new work is then refused with 402 spending_cap_reached)",
            "properties": {
              "cap_usd": {
                "type": "number"
              },
              "used_usd": {
                "type": "number"
              },
              "left_usd": {
                "type": "number"
              },
              "percent": {
                "type": "integer"
              },
              "near": {
                "type": "boolean"
              },
              "reached": {
                "type": "boolean"
              }
            }
          },
          "billing_status": {
            "type": "string",
            "enum": [
              "none",
              "active",
              "past_due",
              "canceled"
            ]
          },
          "payment_required": {
            "type": [
              "string",
              "null"
            ],
            "description": "Why new work is refused, or null"
          },
          "upgrade_url": {
            "type": "string"
          }
        }
      }
    },
    "responses": {
      "E400": {
        "description": "Bad request: the body or a parameter is wrong",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "E401": {
        "description": "No key, or the key is unknown, revoked or expired",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "E402": {
        "description": "No plan (plan_required), a plan limit reached (plan_limit, with limit_name, limit, used, plan, next_plan), a feature on a higher plan (plan_feature), a failed payment (payment_required) or the spending cap reached (spending_cap_reached). Relay agent_message to the person; upgrade_url is where they act",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "E403": {
        "description": "The key lacks the scope this needs; on a file route, the sandbox refused the path (forbidden: permission denied, read-only)",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "E404": {
        "description": "Not found (another org's resources are also not found)",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "E409": {
        "description": "Wrong state for this, e.g. sleeping an already deleted sandbox",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "E410": {
        "description": "Gone: the sign-in expired or was already used (expired_token)",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "E428": {
        "description": "Not yet: the sign-in is waiting for approval in the browser (authorization_pending)",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "E422": {
        "description": "Refused: the upload does not verify (scorecard_invalid)",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "E423": {
        "description": "The organization is frozen (org_frozen): an owner or admin used the Security Center kill switch, and this write is refused until it is unfrozen. Reads, deletes, sleeps and incident-response calls still work",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "E429": {
        "description": "Quota: too many active sandboxes (quota_exceeded, with limit, agent_message and request_url; a create, a fork or a wake; ask for more with POST /v1/limits/request), a rate limit, or polling too fast (slow_down)",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "E413": {
        "description": "Too large: a request body past Cloudflare's 100 MB (send parts with offset=, or use files_url or a link), past 4 GiB on a host, or past 8 MiB on a host that does not stream files",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "E416": {
        "description": "The Range starts past the end of the file (range_not_satisfiable); Content-Range says its size",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "E501": {
        "description": "Not available on this sandbox's host yet (not_available): its k8agent predates the feature",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "E502": {
        "description": "The host failed",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "E503": {
        "description": "No capacity right now, or a wake failed; try again shortly",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "E507": {
        "description": "The sandbox's disk is full (insufficient_storage)",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "E504": {
        "description": "A buffered exec ran past its 90 s limit, or past its own timeout_s, and was stopped (exec_timeout, with limit_s); send stream: true for longer commands",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    }
  },
  "webhooks": {
    "event": {
      "post": {
        "summary": "A webhook delivery",
        "description": "Signed with Kosa8-Signature: t=<unix s>,v1=<hex HMAC-SHA256(secret, \"<t>.<body>\")>. Also sends Kosa8-Event and Kosa8-Delivery.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "type": {
                    "type": "string",
                    "enum": [
                      "sandbox.created",
                      "sandbox.deleted",
                      "sandbox.slept",
                      "sandbox.woke",
                      "sandbox.error",
                      "sandbox.killed",
                      "sandbox.oom",
                      "function.deployed",
                      "function.invocation.failed",
                      "spending_cap.reached",
                      "plan.purchased",
                      "plan.changed",
                      "plan.canceled",
                      "plan.renewed",
                      "plan.payment_failed",
                      "seats.changed",
                      "plan_required.blocked",
                      "plan_limit.near",
                      "plan_limit.reached",
                      "plan_feature.blocked",
                      "hours.reset",
                      "capacity.unavailable",
                      "legacy_access.ending",
                      "legacy_access.ended",
                      "addon.purchased",
                      "addon.canceled",
                      "agent.tool_call.blocked",
                      "agent.tool_call.decided",
                      "webhook.test"
                    ]
                  },
                  "created_at": {
                    "type": "integer"
                  },
                  "org_id": {
                    "type": "string"
                  },
                  "data": {
                    "type": "object"
                  }
                },
                "required": [
                  "id",
                  "type",
                  "created_at",
                  "org_id",
                  "data"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Any 2xx acknowledges it; anything else is retried"
          }
        }
      }
    }
  }
}