{"openapi":"3.0.0","info":{"version":"1.0.0","title":"Aquanode Orchestrator API","description":"API documentation for the Aquanode deployment orchestrator."},"servers":[{"url":"/api/v1"}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"aq_sk_ API key","description":"An Aquanode API key, created under API keys in the console, sent as `Authorization: Bearer aq_sk_...` (or in the `x-api-key` header). A key is scoped to the team that created it; mutating routes need a key with the `deploy` or `full` scope."}},"schemas":{"ServiceConfig":{"allOf":[{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["VMS"]},"vmSlug":{"type":"string"},"template":{"type":"string","enum":["comfyui","torch_and_jupyter"]},"env":{"type":"array","items":{"type":"string"}},"sshKeyId":{"type":"string","minLength":1},"sshPassword":{"type":"string"},"snapshotterConfig":{"type":"string","default":"aquanode"},"setupScript":{"type":"string"},"firewallRules":{"type":"array","items":{"type":"string"}},"post_deployment":{"type":"object","properties":{"startup_script_id":{"type":"string"},"restore_from_deployment":{"type":"string"},"enable_metrics":{"type":"boolean"},"enable_backups":{"type":"boolean"},"attach_workspace":{"type":"string"},"attach_model":{"type":"object","properties":{"source":{"type":"string","enum":["huggingface"]},"repoId":{"type":"string","minLength":1},"revision":{"type":"string","minLength":1},"placement":{"type":"string","enum":["hf_cache","comfyui_dir"],"default":"hf_cache"},"comfyuiDir":{"type":"string","minLength":1},"hfToken":{"type":"string","minLength":1}},"required":["source","repoId"]}}}},"required":["type","vmSlug","sshKeyId"]},{"type":"object","properties":{"logsStorageConfig":{"type":"string"},"type":{"type":"string","enum":["DOCKER_IMAGE"]},"image":{"type":"string"},"tag":{"type":"string","default":"latest"},"command":{"type":"array","items":{"type":"string"}},"snapshotterConfig":{"type":"string","default":"aquanode"},"args":{"type":"array","items":{"type":"string"}},"dockerSlug":{"type":"string"}},"required":["type","image","dockerSlug"]}]},{"type":"object","properties":{"env":{"type":"array","items":{"type":"string"}},"appPort":{"type":"number"},"appPorts":{"type":"array","items":{"type":"number"}}}}]},"Provider":{"type":"object","properties":{"name":{"type":"string","enum":["akash","voltagepark","datacrunch","hotaisle","vastai","massecompute","cudocompute","hyperstack","vultr","simplepod","runpod","nebius","jarvislabs","aws"],"description":"The cloud provider to use for the deployment"}},"required":["name"]},"CreateDeployment":{"type":"object","properties":{"resource":{"type":"object","properties":{"cpu":{"type":"number","minimum":1},"name":{"type":"string"},"memory":{"type":"string"},"storage":{"type":"string"},"region":{"type":"string"},"gpuUnits":{"type":"number"},"gpuModel":{"type":"string"},"desiredInstanceId":{"type":"string"},"location_id":{"type":"string"},"cloud_type":{"type":"string","enum":["secure","community"]}},"required":["cpu","memory","storage"]},"provider":{"$ref":"#/components/schemas/Provider"},"serviceConfig":{"$ref":"#/components/schemas/ServiceConfig"},"idlePolicy":{"type":"object","properties":{"warnAfterMinutes":{"type":"integer","minimum":0,"exclusiveMinimum":true},"actAfterMinutes":{"type":"integer","minimum":0,"exclusiveMinimum":true},"gpuIdleThresholdPercent":{"type":"number","minimum":0,"maximum":100},"autoStopEnabled":{"type":"boolean"}}},"ephemeralTtlMinutes":{"type":"number","minimum":0,"exclusiveMinimum":true},"maxPricePerHourUsd":{"type":"number","minimum":0,"exclusiveMinimum":true},"payWith":{"type":"string","enum":["credits","own_accounts"]}},"required":["resource","provider","serviceConfig"]},"UpDeployment":{"type":"object","properties":{"template":{"type":"string","enum":["comfyui","torch_and_jupyter"]},"sshKeyId":{"type":"string","minLength":1},"name":{"type":"string","minLength":1,"maxLength":120},"gpuModel":{"type":"string"},"maxPrice":{"type":"number","minimum":0,"exclusiveMinimum":true},"provider":{"type":"string","enum":["akash","voltagepark","datacrunch","hotaisle","vastai","massecompute","cudocompute","hyperstack","vultr","simplepod","runpod","nebius","jarvislabs","aws"]},"gpuCount":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":8},"idlePolicy":{"type":"object","properties":{"warnAfterMinutes":{"type":"integer","minimum":0,"exclusiveMinimum":true},"actAfterMinutes":{"type":"integer","minimum":0,"exclusiveMinimum":true},"gpuIdleThresholdPercent":{"type":"number","minimum":0,"maximum":100},"autoStopEnabled":{"type":"boolean"}}},"ephemeralTtlMinutes":{"type":"number","minimum":0,"exclusiveMinimum":true}},"required":["sshKeyId"]},"DeployFromSnapshot":{"type":"object","properties":{"snapshotSource":{"type":"string","minLength":1},"sshKeyId":{"type":"string","minLength":1},"template":{"type":"string","enum":["comfyui","torch_and_jupyter"]},"name":{"type":"string","minLength":1,"maxLength":120},"gpuModel":{"type":"string"},"maxPrice":{"type":"number","minimum":0,"exclusiveMinimum":true},"provider":{"type":"string","enum":["akash","voltagepark","datacrunch","hotaisle","vastai","massecompute","cudocompute","hyperstack","vultr","simplepod","runpod","nebius","jarvislabs","aws"]},"gpuCount":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":8},"idlePolicy":{"type":"object","properties":{"warnAfterMinutes":{"type":"integer","minimum":0,"exclusiveMinimum":true},"actAfterMinutes":{"type":"integer","minimum":0,"exclusiveMinimum":true},"gpuIdleThresholdPercent":{"type":"number","minimum":0,"maximum":100},"autoStopEnabled":{"type":"boolean"}}},"ephemeralTtlMinutes":{"type":"number","minimum":0,"exclusiveMinimum":true}},"required":["snapshotSource","sshKeyId"]},"GetDeploymentsQuery":{"type":"object","properties":{"type":{"type":"string","nullable":true,"enum":["VMS","DOCKER_IMAGE"]},"provider":{"type":"string","enum":["akash","voltagepark","datacrunch","hotaisle","vastai","massecompute","cudocompute","hyperstack","vultr","simplepod","runpod","nebius","jarvislabs","aws"]},"sortByTime":{"type":"boolean"}}},"TeamPlanSummary":{"type":"object","properties":{"tier":{"type":"string","enum":["creator","studio","team","general"]},"status":{"type":"string","enum":["active","past_due","canceled","revoked"]},"currentPeriodEnd":{"type":"string"},"grantCredits":{"type":"number"},"usedCredits":{"type":"number"},"remainingCredits":{"type":"number"},"cancelAtPeriodEnd":{"type":"boolean"}},"required":["tier","status","currentPeriodEnd","grantCredits","usedCredits","remainingCredits","cancelAtPeriodEnd"]},"PlanCheckout":{"type":"object","properties":{"tier":{"type":"string","enum":["creator","studio","team","general"]}},"required":["tier"]},"ApplyReferralCode":{"type":"object","properties":{"referralCode":{"type":"string","minLength":1,"maxLength":20,"description":"The referral code to apply","example":"AQUA123"}},"required":["referralCode"]},"CreateApiKey":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"scopes":{"type":"array","items":{"type":"string","enum":["read","deploy","full","storage"]},"minItems":1},"expiresAt":{"type":"string","nullable":true,"format":"date-time"}},"required":["name","scopes"]},"StartDeviceAuth":{"type":"object","properties":{"clientName":{"type":"string","minLength":1,"maxLength":120},"scopes":{"type":"array","items":{"type":"string","enum":["read","deploy","full","storage"]},"minItems":1}}},"PollDeviceAuth":{"type":"object","properties":{"deviceCode":{"type":"string","minLength":1}},"required":["deviceCode"]},"DeviceUserCode":{"type":"object","properties":{"userCode":{"type":"string","minLength":1}},"required":["userCode"]},"ApproveDeviceAuth":{"type":"object","properties":{"userCode":{"type":"string","minLength":1},"teamId":{"type":"string","minLength":1}},"required":["userCode"]},"SubmitFeedback":{"type":"object","properties":{"category":{"type":"string","enum":["general","bug","feature_request","performance","ui_ux"],"default":"general"},"message":{"type":"string","minLength":1,"maxLength":2000}},"required":["message"]},"FeedbackResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"userId":{"type":"string"},"rating":{"type":"integer","minimum":1,"maximum":5},"category":{"type":"string","enum":["general","bug","feature_request","performance","ui_ux"]},"message":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","userId","rating","category","message","createdAt","updatedAt"]}},"parameters":{}},"paths":{"/connector/sessions":{"post":{"summary":"Register a connector session","description":"Called by `aq connect` with an API key (`deploy` scope) and `x-team-id`. Returns a session token (`aq_cs_...`, stored hashed, 24 h) that authenticates the long-poll, heartbeat, result and end routes. The provider key itself never appears in any request, only its fingerprint. The responses on every connector route are bare JSON, not the `{ success, data }` envelope.","tags":["Connector"],"security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"executorVersion":{"type":"string","example":"mjolnir v1.2.3"},"os":{"type":"string","example":"darwin"},"arch":{"type":"string","example":"arm64"},"providers":{"type":"array","items":{"type":"object","properties":{"provider":{"type":"string","example":"runpod"},"keyFingerprint":{"type":"string","example":"sha256:ab12cd34ef56ab78"},"label":{"type":"string","nullable":true}},"required":["provider","keyFingerprint"]}}},"required":["executorVersion","os","arch","providers"]}}}},"responses":{"201":{"description":"Session registered","content":{"application/json":{"schema":{"type":"object","properties":{"sessionId":{"type":"string"},"sessionToken":{"type":"string","example":"aq_cs_..."},"expiresAt":{"type":"string"},"pollPath":{"type":"string"}},"required":["sessionId","sessionToken","expiresAt","pollPath"]}}}},"400":{"description":"Unknown provider name or malformed fingerprint"},"404":{"description":"CONNECTOR_ENABLED is off, or the team is not on the allowlist"}}}},"/connector/sessions/{id}/requests":{"get":{"summary":"Long-poll for relayed requests","description":"Session token auth. Atomically claims (FOR UPDATE SKIP LOCKED) the oldest queued request for the session team whose provider the session holds a key for, and returns it; 204 after `wait` seconds with nothing. Two laptops on one team never execute the same request.","tags":["Connector"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","example":"25"},"required":false,"name":"wait","in":"query"}],"responses":{"200":{"description":"A claimed request","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"deploymentId":{"type":"string","nullable":true},"provider":{"type":"string"},"method":{"type":"string"},"path":{"type":"string"},"query":{"type":"object","additionalProperties":{"nullable":true}},"headers":{"type":"object","additionalProperties":{"nullable":true}},"body":{"nullable":true},"timeoutSeconds":{"type":"number"},"heartbeatSeconds":{"type":"number"}},"required":["id","deploymentId","provider","method","path","query","headers","timeoutSeconds","heartbeatSeconds"]}}}},"204":{"description":"Nothing queued"},"401":{"description":"Invalid or expired session token"}}}},"/connector/requests/{id}/heartbeat":{"post":{"summary":"Heartbeat a running relayed request","description":"Every `heartbeatSeconds`. A running request with no heartbeat for 3 intervals is stale: the orchestrator treats it as UNKNOWN, never as failed. 409 means the request is no longer running for this session and the executor should stop.","tags":["Connector"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Recorded","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}},"required":["ok"]}}}},"409":{"description":"Not running for this session"}}}},"/connector/requests/{id}/result":{"post":{"summary":"Post the result of a relayed request","description":"The HTTP status and JSON body the local handler produced, or `{ status: 0, error }` when the executor could not run it. A result that arrives after the deadline is kept on the expired row (`late: true`).","tags":["Connector"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status, or 0 when the executor could not run it"},"body":{"nullable":true},"error":{"type":"string"}},"required":["status"]}}}},"responses":{"200":{"description":"Recorded","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"late":{"type":"boolean"}},"required":["ok","late"]}}}},"404":{"description":"No such request for this session"},"409":{"description":"Request already has a result"}}}},"/connector/sessions/{id}":{"delete":{"summary":"End a connector session","tags":["Connector"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"204":{"description":"Ended"}}}},"/connector/status":{"get":{"summary":"Connector status for the team","description":"Online sessions (seen within 60 s) and `verifiedProviders`: the providers that are both online and in the server-side verified list, i.e. the only ones a connector deploy may use.","tags":["Connector"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Status, in the standard success envelope","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"enabled":{"type":"boolean"},"online":{"type":"boolean"},"sessions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"lastSeenAt":{"type":"string"},"executorVersion":{"type":"string"},"providers":{"type":"array","items":{"type":"object","properties":{"provider":{"type":"string","example":"runpod"},"keyFingerprint":{"type":"string","example":"sha256:ab12cd34ef56ab78"},"label":{"type":"string","nullable":true}},"required":["provider","keyFingerprint"]}}},"required":["id","lastSeenAt","executorVersion","providers"]}},"verifiedProviders":{"type":"array","items":{"type":"string"}}},"required":["enabled","online","sessions","verifiedProviders"]},"message":{"type":"string"},"timestamp":{"type":"string"}},"required":["success","data","timestamp"]}}}},"404":{"description":"CONNECTOR_ENABLED is off, or the team is not on the allowlist"}}}},"/connector/providers":{"get":{"summary":"Providers on the multi-cloud console","description":"Each provider the local executor accepts credentials for, with the fields the console asks for. Mirrors the allowlist in mjolnir local; aws is excluded.","tags":["Connector"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Providers, in the standard success envelope","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"providers":{"type":"array","items":{"type":"object","properties":{"provider":{"type":"string"},"displayName":{"type":"string"},"fields":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"label":{"type":"string"},"secret":{"type":"boolean"}},"required":["name","label","secret"]}}},"required":["provider","displayName","fields"]}}},"required":["providers"]},"message":{"type":"string"},"timestamp":{"type":"string"}},"required":["success","data","timestamp"]}}}},"404":{"description":"CONNECTOR_ENABLED is off, or the team is not on the allowlist"}}}},"/deployments":{"get":{"summary":"List deployments","description":"Retrieves all deployments for the current team, with optional filtering.","tags":["Deployments"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","nullable":true,"enum":["VMS","DOCKER_IMAGE"]},"required":false,"name":"type","in":"query"},{"schema":{"type":"string","enum":["akash","voltagepark","datacrunch","hotaisle","vastai","massecompute","cudocompute","hyperstack","vultr","simplepod","runpod","nebius","jarvislabs","aws"]},"required":false,"name":"provider","in":"query"},{"schema":{"type":"boolean"},"required":false,"name":"sortByTime","in":"query"}],"responses":{"200":{"description":"Deployments retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"nullable":true}},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:09.667Z"}},"required":["success","data","timestamp"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:09.668Z"}},"required":["success","error","timestamp"]}}}}}}},"/deployments/{deploymentId}":{"get":{"summary":"Get deployment details","description":"Retrieves detailed information about a specific deployment.","tags":["Deployments"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"deploymentId","in":"path"}],"responses":{"200":{"description":"Deployment details retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"nullable":true},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:09.668Z"}},"required":["success","timestamp"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:09.668Z"}},"required":["success","error","timestamp"]}}}},"404":{"description":"Deployment not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:09.668Z"}},"required":["success","error","timestamp"]}}}}}}},"/deployments/deploy":{"post":{"summary":"Create deployment","description":"Triggers the creation of a new deployment based on the provided configuration.","tags":["Deployments"],"security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDeployment"}}}},"responses":{"200":{"description":"Deployment triggered successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"nullable":true},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:09.668Z"}},"required":["success","timestamp"]}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:09.668Z"}},"required":["success","error","timestamp"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:09.668Z"}},"required":["success","error","timestamp"]}}}}}}},"/deployments/up":{"post":{"summary":"Rent the cheapest matching GPU","description":"Rents the cheapest GPU matching the optional filters and brings up a box, with an optional template, in one call. Bills the team. Needs an API key with the deploy or full scope.","tags":["Deployments"],"security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpDeployment"}}}},"responses":{"200":{"description":"Deployment triggered successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"nullable":true},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:09.668Z"}},"required":["success","timestamp"]}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:09.668Z"}},"required":["success","error","timestamp"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:09.668Z"}},"required":["success","error","timestamp"]}}}},"403":{"description":"API key lacks the deploy scope","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:09.668Z"}},"required":["success","error","timestamp"]}}}}}}},"/deployments/{deploymentId}/status":{"get":{"summary":"Get deployment status","description":"Status of a deployment with its job information and, for a live VM, the on-box agent status.","tags":["Deployments"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"deploymentId","in":"path"}],"responses":{"200":{"description":"Deployment status retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"nullable":true},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:09.668Z"}},"required":["success","timestamp"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:09.668Z"}},"required":["success","error","timestamp"]}}}},"404":{"description":"Deployment not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:09.668Z"}},"required":["success","error","timestamp"]}}}}}}},"/deployments/close":{"post":{"summary":"Close deployment","description":"Closes an active deployment.","tags":["Deployments"],"security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"deploymentId":{"type":"integer"}},"required":["deploymentId"]}}}},"responses":{"200":{"description":"Deployment closed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"nullable":true},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:09.669Z"}},"required":["success","timestamp"]}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:09.669Z"}},"required":["success","error","timestamp"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:09.669Z"}},"required":["success","error","timestamp"]}}}}}}},"/deployments/analytics":{"get":{"summary":"Get deployment analytics","description":"Retrieves analytics and usage data for all team deployments.","tags":["Deployments"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Analytics retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"nullable":true},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:09.669Z"}},"required":["success","timestamp"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:09.669Z"}},"required":["success","error","timestamp"]}}}}}}},"/credits":{"get":{"summary":"Get team credits","description":"Retrieves the total available credits for the current team, and the team's prepaid plan (with `source` `polar` or `comp`; null when it has none, { status: 'unknown' } when the plan lookup failed and only the balance is trustworthy), and tiersOnSale (the plan tiers checkout currently accepts; empty while plans are switched off). remainingCredits is 0 once the current grant has expired. Every field named *Credits is in credits (100 credits = $1); currentPeriodEnd is ISO 8601 UTC.","tags":["Credits"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Team credits retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"credits":{"type":"number"},"plan":{"anyOf":[{"$ref":"#/components/schemas/TeamPlanSummary"},{"type":"object","properties":{"status":{"type":"string","enum":["unknown"]}},"required":["status"]},{"nullable":true}]},"tiersOnSale":{"type":"array","items":{"type":"string","enum":["creator","studio","team","general"]}},"line":{"type":"string","enum":["comfy","general"]},"payWith":{"type":"object","properties":{"default":{"type":"string","enum":["credits","own_accounts"]},"options":{"type":"array","items":{"type":"string","enum":["credits","own_accounts"]}}},"required":["default","options"]},"connector":{"type":"object","properties":{"enabled":{"type":"boolean"},"online":{"type":"boolean"},"providers":{"type":"array","items":{"type":"string"}}},"required":["enabled","online","providers"]}},"required":["credits","plan","tiersOnSale"]},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.095Z"}},"required":["success","data","timestamp"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.095Z"}},"required":["success","error","timestamp"]}}}}}}},"/credits/details":{"get":{"summary":"Get detailed credit info","description":"Retrieves comprehensive credit usage statistics and transaction history.","tags":["Credits"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Detailed credit info retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"currentCredits":{"type":"number"},"totalSpent":{"type":"number"},"totalPurchased":{"type":"number"},"usageStatistics":{"type":"object","properties":{"averageDailyUsage":{"type":"number"},"estimatedDaysRemaining":{"type":"number","nullable":true},"dailyUsage":{"type":"object","additionalProperties":{"type":"number"}}},"required":["averageDailyUsage","estimatedDaysRemaining","dailyUsage"]},"recentTransactions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"amount":{"type":"number"},"timestamp":{"type":"string"},"deploymentId":{"type":"string","nullable":true},"balanceAfter":{"type":"number"},"metadata":{"nullable":true}},"required":["id","type","amount","timestamp","deploymentId","balanceAfter"]}},"summary":{"type":"object","properties":{"lifetimeSpent":{"type":"number"},"lifetimePurchased":{"type":"number"},"netUsage":{"type":"number"},"transactionCount":{"type":"number"}},"required":["lifetimeSpent","lifetimePurchased","netUsage","transactionCount"]}},"required":["currentCredits","totalSpent","totalPurchased","usageStatistics","recentTransactions","summary"]},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.095Z"}},"required":["success","data","timestamp"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.095Z"}},"required":["success","error","timestamp"]}}}}}}},"/credits/plans/checkout":{"post":{"summary":"Start a prepaid plan checkout","description":"Creates a Polar checkout for a monthly plan and returns its URL. Each paid period grants GPU credit at face value into the team wallet; unused plan credit expires at period end plus 24 hours. Answers 503 (reason plans_disabled) while plans are switched off and 409 (reason plan_exists) when the team already has a live plan, or 409 (code wrong_console) when the tier belongs to the other console.","tags":["Credits"],"security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanCheckout"}}}},"responses":{"200":{"description":"Plan checkout created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"checkoutUrl":{"type":"string"}},"required":["checkoutUrl"]},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.095Z"}},"required":["success","data","timestamp"]}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.095Z"}},"required":["success","error","timestamp"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.104Z"}},"required":["success","error","timestamp"]}}}},"409":{"description":"The team already has a plan","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.104Z"}},"required":["success","error","timestamp"]}}}},"503":{"description":"Plans are not available yet","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.104Z"}},"required":["success","error","timestamp"]}}}}}}},"/credits/plans/portal":{"get":{"summary":"Open the plan customer portal","description":"Returns a Polar customer-portal URL where the customer cancels the plan or changes the card on file. Requires the full API key scope when called with an API key.","tags":["Credits"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Plan portal link created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"portalUrl":{"type":"string"}},"required":["portalUrl"]},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.104Z"}},"required":["success","data","timestamp"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.104Z"}},"required":["success","error","timestamp"]}}}},"403":{"description":"API key missing the full scope","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.104Z"}},"required":["success","error","timestamp"]}}}},"404":{"description":"The team has no plan","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.104Z"}},"required":["success","error","timestamp"]}}}}}}},"/marketplace":{"get":{"summary":"Get marketplace data","description":"Retrieves current marketplace data including available providers and GPU pricing.","tags":["Marketplace"],"responses":{"200":{"description":"Marketplace data retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"nullable":true},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.287Z"}},"required":["success","timestamp"]}}}}}}},"/marketplace/cached":{"get":{"summary":"Get cached marketplace data","description":"Retrieves cached marketplace data for faster response times.","tags":["Marketplace"],"responses":{"200":{"description":"Cached marketplace data retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"nullable":true},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.287Z"}},"required":["success","timestamp"]}}}}}}},"/marketplace/breakdown":{"get":{"summary":"Get GPU breakdown","description":"Retrieves detailed breakdown of GPU availability and pricing.","tags":["Marketplace"],"responses":{"200":{"description":"GPU breakdown retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"nullable":true},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.287Z"}},"required":["success","timestamp"]}}}}}}},"/marketplace/provider-status":{"get":{"summary":"Get marketplace provider read status","description":"Retrieves structured per-provider read status for the current marketplace fetch cycle: read-OK (offer count may legitimately be 0), read-FAILED, or read-STALE with the served snapshot age, keyed by provider name.","tags":["Marketplace"],"responses":{"200":{"description":"Marketplace provider read status retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"nullable":true},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.288Z"}},"required":["success","timestamp"]}}}}}}},"/marketplace/quick-picks":{"get":{"summary":"Get user quick picks","description":"Retrieves personalized quick pick deployment options for the current user.","tags":["Marketplace"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Quick picks retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"nullable":true},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.288Z"}},"required":["success","timestamp"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.288Z"}},"required":["success","error","timestamp"]}}}}}}},"/settings":{"get":{"summary":"Get user settings","description":"Retrieves the current user's profile and settings.","tags":["User Settings"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"User settings retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"user_id":{"type":"string","format":"uuid"},"name":{"type":"string","nullable":true},"email":{"type":"string"},"street_address":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state_province":{"type":"string","nullable":true},"country":{"type":"string","nullable":true},"company_name":{"type":"string","nullable":true},"tax_id":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","user_id","name","email","street_address","city","state_province","country","company_name","tax_id","created_at","updated_at"]},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.294Z"}},"required":["success","data","timestamp"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.294Z"}},"required":["success","error","timestamp"]}}}}}},"post":{"summary":"Upsert user settings","description":"Creates or updates user settings.","tags":["User Settings"],"security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string","format":"email"},"street_address":{"type":"string"},"city":{"type":"string"},"state_province":{"type":"string"},"country":{"type":"string"},"company_name":{"type":"string"},"tax_id":{"type":"string"}},"required":["email"]}}}},"responses":{"200":{"description":"User settings upserted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"user_id":{"type":"string","format":"uuid"},"name":{"type":"string","nullable":true},"email":{"type":"string"},"street_address":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state_province":{"type":"string","nullable":true},"country":{"type":"string","nullable":true},"company_name":{"type":"string","nullable":true},"tax_id":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","user_id","name","email","street_address","city","state_province","country","company_name","tax_id","created_at","updated_at"]},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.294Z"}},"required":["success","data","timestamp"]}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.294Z"}},"required":["success","error","timestamp"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.294Z"}},"required":["success","error","timestamp"]}}}}}},"patch":{"summary":"Update user settings","description":"Partially updates user settings.","tags":["User Settings"],"security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string","format":"email"},"street_address":{"type":"string"},"city":{"type":"string"},"state_province":{"type":"string"},"country":{"type":"string"},"company_name":{"type":"string"},"tax_id":{"type":"string"}}}}}},"responses":{"200":{"description":"User settings updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"user_id":{"type":"string","format":"uuid"},"name":{"type":"string","nullable":true},"email":{"type":"string"},"street_address":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state_province":{"type":"string","nullable":true},"country":{"type":"string","nullable":true},"company_name":{"type":"string","nullable":true},"tax_id":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","user_id","name","email","street_address","city","state_province","country","company_name","tax_id","created_at","updated_at"]},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.294Z"}},"required":["success","data","timestamp"]}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.294Z"}},"required":["success","error","timestamp"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.294Z"}},"required":["success","error","timestamp"]}}}}}}},"/settings/ssh-keys":{"get":{"summary":"List SSH keys","description":"Retrieves the current user's SSH keys. When the request carries an `x-team-id` header for a team the caller belongs to, keys other members have shared with that team are included too, each flagged with `is_mine` / `is_team_shared` plus the owner's email and name.","tags":["User Settings"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"SSH keys retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"user_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"public_key":{"type":"string"},"key_type":{"type":"string"},"fingerprint":{"type":"string"},"is_active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","user_id","name","public_key","key_type","fingerprint","is_active","created_at","updated_at"]}},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.294Z"}},"required":["success","data","timestamp"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.294Z"}},"required":["success","error","timestamp"]}}}}}},"post":{"summary":"Add SSH key","description":"Adds a new SSH public key to the user's account.","tags":["User Settings"],"security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"public_key":{"type":"string","minLength":1,"pattern":"^(ssh-(rsa|dss|ed25519)|ecdsa-sha2-nistp(256|384|521)) [A-Za-z0-9+/=]+(?: [^\\r\\n]+)?$"},"name":{"type":"string"}},"required":["public_key"]}}}},"responses":{"200":{"description":"SSH key added successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"user_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"public_key":{"type":"string"},"key_type":{"type":"string"},"fingerprint":{"type":"string"},"is_active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","user_id","name","public_key","key_type","fingerprint","is_active","created_at","updated_at"]},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.294Z"}},"required":["success","data","timestamp"]}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.294Z"}},"required":["success","error","timestamp"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.294Z"}},"required":["success","error","timestamp"]}}}}}}},"/settings/ssh-keys/{keyId}":{"patch":{"summary":"Update SSH key","description":"Updates an existing SSH key.","tags":["User Settings"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"keyId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"public_key":{"type":"string","minLength":1},"name":{"type":"string","minLength":1}}}}}},"responses":{"200":{"description":"SSH key updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"user_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"public_key":{"type":"string"},"key_type":{"type":"string"},"fingerprint":{"type":"string"},"is_active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","user_id","name","public_key","key_type","fingerprint","is_active","created_at","updated_at"]},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.294Z"}},"required":["success","data","timestamp"]}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.294Z"}},"required":["success","error","timestamp"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.294Z"}},"required":["success","error","timestamp"]}}}},"404":{"description":"SSH key not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.294Z"}},"required":["success","error","timestamp"]}}}}}},"delete":{"summary":"Delete SSH key","description":"Removes an SSH key from the user's account.","tags":["User Settings"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"keyId","in":"path"}],"responses":{"200":{"description":"SSH key deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"nullable":true},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.294Z"}},"required":["success","timestamp"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.294Z"}},"required":["success","error","timestamp"]}}}},"404":{"description":"SSH key not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.294Z"}},"required":["success","error","timestamp"]}}}},"409":{"description":"Key is shared with the team and still attached to another member live deployment","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.294Z"}},"required":["success","error","timestamp"]}}}}}}},"/settings/ssh-keys/{keyId}/share":{"patch":{"summary":"Share or unshare an SSH key with your team","description":"Shares one of your OWN keys with the team named by the `x-team-id` header, so any member of that team can select it when deploying, or withdraws that sharing. The team is always taken from the header (membership is verified); it is never accepted from the body. Sharing does not transfer ownership — only the owner can rename, delete or unshare the key.","tags":["User Settings"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"keyId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"share":{"type":"boolean"}},"required":["share"]}}}},"responses":{"200":{"description":"SSH key sharing updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"user_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"public_key":{"type":"string"},"key_type":{"type":"string"},"fingerprint":{"type":"string"},"is_active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","user_id","name","public_key","key_type","fingerprint","is_active","created_at","updated_at"]},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.294Z"}},"required":["success","data","timestamp"]}}}},"400":{"description":"Invalid request data, or share=true with no team context","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.294Z"}},"required":["success","error","timestamp"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.294Z"}},"required":["success","error","timestamp"]}}}},"403":{"description":"You can only share SSH keys that you own","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.294Z"}},"required":["success","error","timestamp"]}}}}}}},"/settings/connections":{"get":{"summary":"List user connections","description":"Retrieves all external account connections (e.g., GitHub, Google).","tags":["User Settings"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"User connections retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"nullable":true}},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.295Z"}},"required":["success","data","timestamp"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.295Z"}},"required":["success","error","timestamp"]}}}}}},"post":{"summary":"Create user connection","description":"Connects an external account.","tags":["User Settings"],"security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"type":"string","enum":["github","google"]},"provider_user_id":{"type":"string"}},"required":["provider","provider_user_id"]}}}},"responses":{"200":{"description":"User connection created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"nullable":true},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.295Z"}},"required":["success","timestamp"]}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.295Z"}},"required":["success","error","timestamp"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.295Z"}},"required":["success","error","timestamp"]}}}}}}},"/settings/integration-configs":{"get":{"summary":"List integration configs","description":"Retrieves storage configurations (S3, Lighthouse, etc.).","tags":["User Settings"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Integration configs retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"nullable":true}},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.295Z"}},"required":["success","data","timestamp"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.295Z"}},"required":["success","error","timestamp"]}}}}}},"post":{"summary":"Create integration config","description":"Adds a new storage integration configuration.","tags":["User Settings"],"security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"key_name":{"type":"string"},"service_type":{"type":"string","enum":["s3","lighthouse"]},"config":{"type":"object","additionalProperties":{"type":"string"}}},"required":["key_name","service_type","config"]}}}},"responses":{"200":{"description":"Integration config created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"nullable":true},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.295Z"}},"required":["success","timestamp"]}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.295Z"}},"required":["success","error","timestamp"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.295Z"}},"required":["success","error","timestamp"]}}}}}}},"/settings/integration-configs/managed-storage":{"get":{"summary":"Resolve Aquanode managed storage","description":"Returns a per-tenant scoped Backblaze B2 application key (never master creds) plus `STORAGE_PREFIX=<teamId>` for a logged-in CLI (`ogre --to aquanode`, #178/CD2) so it can push snapshots under `<bucket>/<teamId>/<backup_id>` (#288/#30). Requires an API key with the `storage` scope (#233) — browser cookie sessions and non-storage/non-full keys are rejected. The client must send `X-Ogre-Managed-Storage-Scoped: 1` to advertise it understands STORAGE_PREFIX; older ogre builds (which would write flat and fail) get HTTP 426.","tags":["User Settings"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Managed storage config resolved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"nullable":true},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.295Z"}},"required":["success","timestamp"]}}}},"401":{"description":"Unauthorized — API key required (cookie sessions rejected)","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.295Z"}},"required":["success","error","timestamp"]}}}},"403":{"description":"Forbidden — API key missing required scope: storage","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.295Z"}},"required":["success","error","timestamp"]}}}},"426":{"description":"Upgrade Required — ogre client does not support tenant-scoped storage","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.295Z"}},"required":["success","error","timestamp"]}}}},"500":{"description":"Managed storage not configured","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.295Z"}},"required":["success","error","timestamp"]}}}}}}},"/settings/preset-scripts":{"get":{"summary":"List preset scripts","description":"Retrieves custom scripts defined by the user.","tags":["User Settings"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Preset scripts retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"nullable":true}},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.295Z"}},"required":["success","data","timestamp"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.295Z"}},"required":["success","error","timestamp"]}}}}}},"post":{"summary":"Create preset script","description":"Adds a new preset script.","tags":["User Settings"],"security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"script":{"type":"string"}},"required":["name","script"]}}}},"responses":{"200":{"description":"Preset script created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"nullable":true},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.295Z"}},"required":["success","timestamp"]}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.306Z"}},"required":["success","error","timestamp"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.307Z"}},"required":["success","error","timestamp"]}}}}}}},"/snapshots/deployments":{"get":{"summary":"Get snapshot supported deployments","description":"Lists all deployments that support snapshotting.","tags":["Snapshots"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Supported deployments retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"nullable":true}},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.382Z"}},"required":["success","data","timestamp"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.382Z"}},"required":["success","error","timestamp"]}}}}}}},"/snapshots/history":{"get":{"summary":"Get user snapshot history","description":"Retrieves the complete snapshot history for the current user.","tags":["Snapshots"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Snapshot history retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"nullable":true}},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.382Z"}},"required":["success","data","timestamp"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.382Z"}},"required":["success","error","timestamp"]}}}}}}},"/snapshots/external":{"post":{"summary":"Register an external/CLI snapshot","description":"Registers a snapshot created by a standalone ogre/aq CLI run that has no Aquanode deployment, recording it as an account-owned, deployment-less backup so it lists + restores in the console /backups.","tags":["Snapshots"],"security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"path":{"type":"string","example":"/root"},"ogre_snapshot_id":{"type":"string","example":"latest"},"name":{"type":"string","example":"my-comfyui-env"},"size":{"type":"number","example":1048576}},"required":["path","ogre_snapshot_id"]}}}},"responses":{"200":{"description":"External snapshot registered successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"nullable":true},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.382Z"}},"required":["success","timestamp"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.382Z"}},"required":["success","error","timestamp"]}}}}}}},"/snapshots/{deploymentId}/create":{"post":{"summary":"Create snapshot","description":"Triggers the creation of a new snapshot for a specific deployment.","tags":["Snapshots"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"deploymentId","in":"path"}],"responses":{"200":{"description":"Snapshot creation triggered successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"nullable":true},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.382Z"}},"required":["success","timestamp"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.382Z"}},"required":["success","error","timestamp"]}}}},"404":{"description":"Deployment not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.382Z"}},"required":["success","error","timestamp"]}}}}}}},"/snapshots/share":{"post":{"summary":"Create a link-scoped snapshot share","description":"Generates an unguessable, link-scoped share for a snapshot the caller owns (CD11). Returns the token + public deploy-from-link URL. This is the thin launch-day share loop — not a public catalog.","tags":["Snapshots"],"security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"snapshot_source":{"type":"string","example":"ext-42"},"name":{"type":"string","example":"my-comfyui-env"},"expires_at":{"type":"string","format":"date-time","description":"Optional ISO-8601 hard expiry (#210); omit for a link that never expires","example":"2026-07-01T00:00:00.000Z"}},"required":["snapshot_source"]}}}},"responses":{"200":{"description":"Snapshot share created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"nullable":true},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.382Z"}},"required":["success","timestamp"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.382Z"}},"required":["success","error","timestamp"]}}}}}}},"/snapshots/share/{token}":{"get":{"summary":"Preview a shared snapshot (public)","description":"Unauthenticated preview of a shared snapshot, driving the public deploy-from-link page. Returns only the env description (paths, size, recency) — never the owner. 404 for an unknown or revoked token.","tags":["Snapshots"],"parameters":[{"schema":{"type":"string"},"required":true,"name":"token","in":"path"}],"responses":{"200":{"description":"Snapshot share preview retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"nullable":true},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.383Z"}},"required":["success","timestamp"]}}}},"404":{"description":"Share link not found or has been revoked","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.383Z"}},"required":["success","error","timestamp"]}}}}}}},"/snapshots/shares":{"get":{"summary":"List the caller's snapshot shares","tags":["Snapshots"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Snapshot shares retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"nullable":true}},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.383Z"}},"required":["success","data","timestamp"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.383Z"}},"required":["success","error","timestamp"]}}}}}}},"/snapshots/share/{token}/revoke":{"post":{"summary":"Revoke a snapshot share","tags":["Snapshots"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"token","in":"path"}],"responses":{"200":{"description":"Snapshot share revoked successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"nullable":true},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.383Z"}},"required":["success","timestamp"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.383Z"}},"required":["success","error","timestamp"]}}}},"404":{"description":"Share link not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.383Z"}},"required":["success","error","timestamp"]}}}}}}},"/snapshots/webhook":{"post":{"summary":"Snapshot webhook","description":"Webhook endpoint for snapshot status updates from Ogre.","tags":["Snapshots"],"responses":{"200":{"description":"Webhook processed successfully"}}}},"/snapshots/{source}/visibility":{"patch":{"summary":"Set the visibility of a snapshot series","description":"Sets private / team / public on every series behind a snapshot source (a deployment id or ext-<backupId>). Requires write access; a share link does not grant it.","tags":["Snapshots"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","example":"ext-42"},"required":true,"name":"source","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"visibility":{"type":"string","enum":["private","team","public"]}},"required":["visibility"]}}}},"responses":{"200":{"description":"Snapshot visibility updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"updated":{"type":"number"}},"required":["updated"]},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.383Z"}},"required":["success","data","timestamp"]}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.383Z"}},"required":["success","error","timestamp"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.383Z"}},"required":["success","error","timestamp"]}}}},"403":{"description":"You do not have permission to change this snapshot","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.383Z"}},"required":["success","error","timestamp"]}}}}}}},"/billing/history":{"get":{"summary":"Get team billing history","description":"Retrieves a detailed history of billing events and transactions for the current team.","tags":["Billing"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Billing history retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"amount":{"type":"number"},"type":{"type":"string"},"status":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","amount","type","status","createdAt"]}},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.390Z"}},"required":["success","data","timestamp"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.390Z"}},"required":["success","error","timestamp"]}}}}}}},"/referrals/code":{"get":{"summary":"Get user referral code","description":"Retrieves the current user's unique referral code.","tags":["Referrals"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Referral code retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"code":{"type":"string","example":"AQUA123"}},"required":["code"]},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.459Z"}},"required":["success","data","timestamp"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Referral code not found"}}}},"/referrals/stats":{"get":{"summary":"Get referral statistics","description":"Retrieves statistics about the user's referrals, including count and rewards.","tags":["Referrals"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Referral stats retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"totalReferrals":{"type":"number","example":5},"activeReferrals":{"type":"number","example":3},"totalRewards":{"type":"number","example":150.5}},"required":["totalReferrals","activeReferrals","totalRewards"]},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.459Z"}},"required":["success","data","timestamp"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Referral stats not found"}}}},"/referrals/history":{"get":{"summary":"Get referral history","description":"Retrieves the list of users who signed up with the caller's referral code, with masked emails, per-referral payout status, and credits earned.","tags":["Referrals"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Referral history retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"type":"object","properties":{"referred_user":{"type":"string","example":"pr***@***.com"},"status":{"type":"string","enum":["paid","pending"],"example":"paid"},"signup_bonus_amount":{"type":"number","example":50},"first_payment_bonus_amount":{"type":"number","example":500},"earned_credits":{"type":"number","example":550},"signed_up_at":{"type":"string","example":"2026-04-14T10:00:00.000Z"}},"required":["referred_user","status","signup_bonus_amount","first_payment_bonus_amount","earned_credits","signed_up_at"]}},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.459Z"}},"required":["success","data","timestamp"]}}}},"401":{"description":"Unauthorized"}}}},"/referrals/apply":{"post":{"summary":"Apply a referral code","description":"Allows a new user to apply a referral code within the allowed window.","tags":["Referrals"],"security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApplyReferralCode"}}}},"responses":{"200":{"description":"Referral code applied successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"string","example":"Referral code applied successfully"},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.459Z"}},"required":["success","data","timestamp"]}}}},"400":{"description":"Invalid request data or window expired"},"401":{"description":"Unauthorized"}}}},"/teams":{"get":{"summary":"List user teams","description":"Retrieves all teams the current user is a member of.","tags":["Teams"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"User teams retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"nullable":true}},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.463Z"}},"required":["success","data","timestamp"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.463Z"}},"required":["success","error","timestamp"]}}}}}},"post":{"summary":"Create team","description":"Creates a new team.","tags":["Teams"],"security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1}},"required":["name"]}}}},"responses":{"200":{"description":"Team created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"nullable":true},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.463Z"}},"required":["success","timestamp"]}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.463Z"}},"required":["success","error","timestamp"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.463Z"}},"required":["success","error","timestamp"]}}}}}}},"/teams/default":{"get":{"summary":"Get default team","description":"Retrieves the current user's default team.","tags":["Teams"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Default team retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"nullable":true},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.463Z"}},"required":["success","timestamp"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.463Z"}},"required":["success","error","timestamp"]}}}}}}},"/teams/{teamId}":{"get":{"summary":"Get team details","description":"Retrieves detailed information about a specific team, including members.","tags":["Teams"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"teamId","in":"path"}],"responses":{"200":{"description":"Team details retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"nullable":true},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.463Z"}},"required":["success","timestamp"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.463Z"}},"required":["success","error","timestamp"]}}}},"404":{"description":"Team not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.463Z"}},"required":["success","error","timestamp"]}}}}}},"delete":{"summary":"Delete team","description":"Deletes a team. Only the team owner may delete it.","tags":["Teams"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"teamId","in":"path"}],"responses":{"200":{"description":"Team deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"nullable":true},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.463Z"}},"required":["success","timestamp"]}}}},"400":{"description":"Invalid team ID","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.463Z"}},"required":["success","error","timestamp"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.463Z"}},"required":["success","error","timestamp"]}}}},"403":{"description":"Only team owners can delete the team","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.464Z"}},"required":["success","error","timestamp"]}}}}}}},"/api-keys/teams/{teamId}":{"post":{"summary":"Create API Key","description":"Creates a new API Key for the team.","tags":["API Keys"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"teamId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateApiKey"}}}},"responses":{"200":{"description":"API Key created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"nullable":true},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.470Z"}},"required":["success","timestamp"]}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.470Z"}},"required":["success","error","timestamp"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.470Z"}},"required":["success","error","timestamp"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.470Z"}},"required":["success","error","timestamp"]}}}}}},"get":{"summary":"List API Keys","description":"Lists all API keys for the team.","tags":["API Keys"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"teamId","in":"path"}],"responses":{"200":{"description":"API Keys retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"nullable":true},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.470Z"}},"required":["success","timestamp"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.470Z"}},"required":["success","error","timestamp"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.470Z"}},"required":["success","error","timestamp"]}}}}}}},"/api-keys/teams/{teamId}/{keyId}":{"delete":{"summary":"Revoke API Key","description":"Revokes (deletes) an API Key for the team.","tags":["API Keys"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"teamId","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"keyId","in":"path"}],"responses":{"200":{"description":"API Key revoked successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"nullable":true},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.470Z"}},"required":["success","timestamp"]}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.470Z"}},"required":["success","error","timestamp"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.470Z"}},"required":["success","error","timestamp"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.470Z"}},"required":["success","error","timestamp"]}}}}}}},"/api-keys/device/start":{"post":{"summary":"Start CLI device login","description":"Begins the `aq login` device-grant pairing. Public (unauthenticated): returns a secret deviceCode for polling and a short userCode the user approves in the console.","tags":["API Keys"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartDeviceAuth"}}}},"responses":{"200":{"description":"Device authorization started","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"nullable":true},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.472Z"}},"required":["success","timestamp"]}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.472Z"}},"required":["success","error","timestamp"]}}}}}}},"/api-keys/device/token":{"post":{"summary":"Poll CLI device login","description":"Polls a pairing by its deviceCode. Public. Returns `{ status }` of pending | approved | denied | expired | consumed; on the first approved poll it returns the issued token exactly once.","tags":["API Keys"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PollDeviceAuth"}}}},"responses":{"200":{"description":"Device authorization status","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"nullable":true},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.472Z"}},"required":["success","timestamp"]}}}},"400":{"description":"Unknown or expired device code","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.472Z"}},"required":["success","error","timestamp"]}}}}}}},"/api-keys/device/{userCode}":{"get":{"summary":"Get pairing details","description":"Returns pairing details (scopes, status) for the console approve screen. The requesting machine name is withheld until approval to avoid leaking it on a guessed code. Rate-limited per actor.","tags":["API Keys"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"userCode","in":"path"}],"responses":{"200":{"description":"Pairing details","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"nullable":true},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.472Z"}},"required":["success","timestamp"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.472Z"}},"required":["success","error","timestamp"]}}}},"404":{"description":"Pairing code not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.472Z"}},"required":["success","error","timestamp"]}}}},"429":{"description":"Too many pairing lookups","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.472Z"}},"required":["success","error","timestamp"]}}}}}}},"/api-keys/device/approve":{"post":{"summary":"Approve CLI device login","description":"Approves a pairing as the signed-in user, minting an API key for the team named in `teamId` (owner/admin only) or, when absent, their default team, and staging it for one-time CLI pickup.","tags":["API Keys"],"security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApproveDeviceAuth"}}}},"responses":{"200":{"description":"Pairing approved","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"nullable":true},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.472Z"}},"required":["success","timestamp"]}}}},"400":{"description":"Invalid or expired pairing","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.472Z"}},"required":["success","error","timestamp"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.472Z"}},"required":["success","error","timestamp"]}}}}}}},"/api-keys/device/deny":{"post":{"summary":"Deny CLI device login","description":"Denies a pairing so the CLI stops polling.","tags":["API Keys"],"security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceUserCode"}}}},"responses":{"200":{"description":"Pairing denied","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"nullable":true},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.472Z"}},"required":["success","timestamp"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.472Z"}},"required":["success","error","timestamp"]}}}}}}},"/setups/versions":{"get":{"summary":"List snapshot versions you can see","description":"Your own versions plus any owned by a team you belong to. Pass ?public=true to fold in the public catalog, and ?name= to filter to one series.","tags":["Setups"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":false,"name":"name","in":"query"},{"schema":{"type":"string","enum":["true","false"]},"required":false,"name":"public","in":"query"}],"responses":{"200":{"description":"Snapshot versions retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number","example":7},"name":{"type":"string","example":"comfyui-base"},"version":{"type":"number","example":3},"label":{"type":"string","nullable":true,"example":"stable"},"description":{"type":"string","nullable":true,"example":"ComfyUI with custom nodes"},"visibility":{"type":"string","enum":["private","team","public"],"example":"team"},"path":{"type":"string","example":"/root"},"size_bytes":{"type":"number","nullable":true,"example":1048576},"created_at":{"type":"string","example":"2026-08-21T00:00:00.000Z"},"deployment_count":{"type":"number","example":3},"provenance":{"type":"string","enum":["user","pause","idle_auto","deploy"],"example":"user"},"callable":{"type":"boolean","example":true},"notCallableReason":{"type":"string","nullable":true,"example":"This version has no app to call. Its pod ran no template and defined no entrypoint."},"creator_id":{"type":"string"},"team_id":{"type":"string","nullable":true},"setup_id":{"type":"string"}},"required":["id","name","version","label","description","visibility","path","size_bytes","created_at","deployment_count","provenance","callable","notCallableReason"]}},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.567Z"}},"required":["success","data","timestamp"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.567Z"}},"required":["success","error","timestamp"]}}}}}}},"/setups/versions/public":{"get":{"summary":"The public snapshot version catalog","description":"Versions whose owners published them. Readable and restorable by any authenticated user; never editable or deletable by anyone outside the owning team.","tags":["Setups"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Public snapshot versions retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number","example":7},"name":{"type":"string","example":"comfyui-base"},"version":{"type":"number","example":3},"label":{"type":"string","nullable":true,"example":"stable"},"description":{"type":"string","nullable":true,"example":"ComfyUI with custom nodes"},"visibility":{"type":"string","enum":["private","team","public"],"example":"team"},"path":{"type":"string","example":"/root"},"size_bytes":{"type":"number","nullable":true,"example":1048576},"created_at":{"type":"string","example":"2026-08-21T00:00:00.000Z"},"deployment_count":{"type":"number","example":3},"provenance":{"type":"string","enum":["user","pause","idle_auto","deploy"],"example":"user"},"callable":{"type":"boolean","example":true},"notCallableReason":{"type":"string","nullable":true,"example":"This version has no app to call. Its pod ran no template and defined no entrypoint."},"creator_id":{"type":"string"},"team_id":{"type":"string","nullable":true},"setup_id":{"type":"string"}},"required":["id","name","version","label","description","visibility","path","size_bytes","created_at","deployment_count","provenance","callable","notCallableReason"]}},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.567Z"}},"required":["success","data","timestamp"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.567Z"}},"required":["success","error","timestamp"]}}}}}}},"/setups/versions/{id}":{"get":{"summary":"Get a snapshot version","description":"Returns 404 — not 403 — when you cannot read the version, so the response never confirms that another tenant's version exists.","tags":["Setups"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Snapshot version retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"id":{"type":"number","example":7},"name":{"type":"string","example":"comfyui-base"},"version":{"type":"number","example":3},"label":{"type":"string","nullable":true,"example":"stable"},"description":{"type":"string","nullable":true,"example":"ComfyUI with custom nodes"},"visibility":{"type":"string","enum":["private","team","public"],"example":"team"},"path":{"type":"string","example":"/root"},"size_bytes":{"type":"number","nullable":true,"example":1048576},"created_at":{"type":"string","example":"2026-08-21T00:00:00.000Z"},"deployment_count":{"type":"number","example":3},"provenance":{"type":"string","enum":["user","pause","idle_auto","deploy"],"example":"user"},"callable":{"type":"boolean","example":true},"notCallableReason":{"type":"string","nullable":true,"example":"This version has no app to call. Its pod ran no template and defined no entrypoint."},"creator_id":{"type":"string"},"team_id":{"type":"string","nullable":true},"setup_id":{"type":"string"}},"required":["id","name","version","label","description","visibility","path","size_bytes","created_at","deployment_count","provenance","callable","notCallableReason"]},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.568Z"}},"required":["success","data","timestamp"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.568Z"}},"required":["success","error","timestamp"]}}}},"404":{"description":"Snapshot version not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.568Z"}},"required":["success","error","timestamp"]}}}}}},"patch":{"summary":"Edit a snapshot version's metadata","description":"Only label, description and visibility can change. A body carrying a pinned field (the snapshot id, path, series or version number) is REFUSED rather than ignored — a promoted version is immutable, and a caller who believes they repointed one must be told they did not.","tags":["Setups"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"visibility":{"type":"string","enum":["private","team","public"]}}}}}},"responses":{"200":{"description":"Snapshot version updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"id":{"type":"number","example":7},"name":{"type":"string","example":"comfyui-base"},"version":{"type":"number","example":3},"label":{"type":"string","nullable":true,"example":"stable"},"description":{"type":"string","nullable":true,"example":"ComfyUI with custom nodes"},"visibility":{"type":"string","enum":["private","team","public"],"example":"team"},"path":{"type":"string","example":"/root"},"size_bytes":{"type":"number","nullable":true,"example":1048576},"created_at":{"type":"string","example":"2026-08-21T00:00:00.000Z"},"deployment_count":{"type":"number","example":3},"provenance":{"type":"string","enum":["user","pause","idle_auto","deploy"],"example":"user"},"callable":{"type":"boolean","example":true},"notCallableReason":{"type":"string","nullable":true,"example":"This version has no app to call. Its pod ran no template and defined no entrypoint."},"creator_id":{"type":"string"},"team_id":{"type":"string","nullable":true},"setup_id":{"type":"string"}},"required":["id","name","version","label","description","visibility","path","size_bytes","created_at","deployment_count","provenance","callable","notCallableReason"]},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.568Z"}},"required":["success","data","timestamp"]}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.568Z"}},"required":["success","error","timestamp"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.568Z"}},"required":["success","error","timestamp"]}}}},"403":{"description":"You do not have permission to modify this snapshot version","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.568Z"}},"required":["success","error","timestamp"]}}}},"404":{"description":"Snapshot version not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.568Z"}},"required":["success","error","timestamp"]}}}}}}},"/setups/versions/{id}/deployments":{"get":{"summary":"List your deployments running a snapshot version","description":"Requires write access to the version, and returns only deployments the CALLER owns (their own plus their teams'). A public version may be running on other tenants' boxes; those are never listed. The version's `deployment_count` counts every live box across all tenants, so it can legitimately exceed this list's length — a count names nobody, a list would.","tags":["Setups"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Snapshot version deployments retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"name":{"type":"string","nullable":true},"status":{"type":"string","nullable":true},"provider":{"type":"string","nullable":true},"created_at":{"type":"string"}},"required":["id","name","status","provider","created_at"]}},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.568Z"}},"required":["success","data","timestamp"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.568Z"}},"required":["success","error","timestamp"]}}}},"403":{"description":"You do not have permission to list deployments for this version","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.568Z"}},"required":["success","error","timestamp"]}}}},"404":{"description":"Snapshot version not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.568Z"}},"required":["success","error","timestamp"]}}}}}}},"/setups":{"get":{"summary":"List pods","description":"Pods owned by the current team.","tags":["Setups"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Pods retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"nullable":true}},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.568Z"}},"required":["success","data","timestamp"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.569Z"}},"required":["success","error","timestamp"]}}}}}},"post":{"summary":"Create a pod and start it","description":"Creates the pod, then starts it on the given offer, which rents a billable box. A start the deploy boundary refuses keeps the pod created and stopped, so another offer can be tried with POST /setups/{id}/start. Needs an API key with the deploy or full scope.","tags":["Setups"],"security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"offer":{"type":"object","properties":{"resource":{"type":"object","properties":{"cpu":{"type":"number","minimum":1},"name":{"type":"string"},"memory":{"type":"string"},"storage":{"type":"string"},"region":{"type":"string"},"gpuUnits":{"type":"number"},"gpuModel":{"type":"string"},"desiredInstanceId":{"type":"string","minLength":1},"location_id":{"type":"string"},"cloud_type":{"type":"string","enum":["secure","community"]}},"required":["cpu","memory","storage","desiredInstanceId"]},"provider":{"type":"object","properties":{"name":{"type":"string","enum":["akash","voltagepark","datacrunch","hotaisle","vastai","massecompute","cudocompute","hyperstack","vultr","simplepod","runpod","nebius","jarvislabs","aws"]}},"required":["name"]},"sshKeyId":{"type":"string","minLength":1}},"required":["resource","provider","sshKeyId"]},"maxPricePerHourUsd":{"type":"number","minimum":0,"exclusiveMinimum":true},"payWith":{"type":"string","enum":["credits","own_accounts"]},"environmentVersionId":{"type":"string","format":"uuid"},"volumeId":{"anyOf":[{"type":"string","enum":["new"]},{"type":"string","format":"uuid"},{"nullable":true},{"nullable":true}]},"ports":{"type":"array","items":{"type":"integer","minimum":1,"maximum":65535},"minItems":1},"startupScriptId":{"type":"string","pattern":"^[1-9]\\d{0,9}$"},"model":{"type":"object","properties":{"repo":{"type":"string","minLength":1},"revision":{"type":"string","minLength":1},"placement":{"type":"string","enum":["hf_cache","comfyui_dir"]},"comfyDir":{"type":"string","minLength":1},"hfToken":{"type":"string","minLength":1}},"required":["repo"]}},"required":["offer","environmentVersionId","volumeId"]}}}},"responses":{"201":{"description":"Pod created and starting","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"nullable":true},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.569Z"}},"required":["success","timestamp"]}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.569Z"}},"required":["success","error","timestamp"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.569Z"}},"required":["success","error","timestamp"]}}}},"403":{"description":"API key lacks the deploy scope","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.569Z"}},"required":["success","error","timestamp"]}}}}}}},"/setups/{id}":{"get":{"summary":"Get a pod","tags":["Setups"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Pod retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"nullable":true},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.569Z"}},"required":["success","timestamp"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.569Z"}},"required":["success","error","timestamp"]}}}},"404":{"description":"Pod not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.569Z"}},"required":["success","error","timestamp"]}}}}}}},"/setups/{id}/start":{"post":{"summary":"Start a pod","description":"Rents a box on the given offer and answers 202 with the new deployment id. Needs an API key with the deploy or full scope.","tags":["Setups"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"offer":{"type":"object","properties":{"resource":{"type":"object","properties":{"cpu":{"type":"number","minimum":1},"name":{"type":"string"},"memory":{"type":"string"},"storage":{"type":"string"},"region":{"type":"string"},"gpuUnits":{"type":"number"},"gpuModel":{"type":"string"},"desiredInstanceId":{"type":"string","minLength":1},"location_id":{"type":"string"},"cloud_type":{"type":"string","enum":["secure","community"]}},"required":["cpu","memory","storage","desiredInstanceId"]},"provider":{"type":"object","properties":{"name":{"type":"string","enum":["akash","voltagepark","datacrunch","hotaisle","vastai","massecompute","cudocompute","hyperstack","vultr","simplepod","runpod","nebius","jarvislabs","aws"]}},"required":["name"]},"sshKeyId":{"type":"string","minLength":1}},"required":["resource","provider","sshKeyId"]},"maxPricePerHourUsd":{"type":"number","minimum":0,"exclusiveMinimum":true},"payWith":{"type":"string","enum":["credits","own_accounts"]}},"required":["offer"]}}}},"responses":{"202":{"description":"Pod starting","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"nullable":true},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.569Z"}},"required":["success","timestamp"]}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.569Z"}},"required":["success","error","timestamp"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.569Z"}},"required":["success","error","timestamp"]}}}},"403":{"description":"API key lacks the deploy scope","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.569Z"}},"required":["success","error","timestamp"]}}}},"404":{"description":"Pod not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.569Z"}},"required":["success","error","timestamp"]}}}}}}},"/setups/{id}/stop":{"post":{"summary":"Stop a pod","description":"Queues the stop and answers 202 at once.","tags":["Setups"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"202":{"description":"Pod stopping","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"nullable":true},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.569Z"}},"required":["success","timestamp"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.569Z"}},"required":["success","error","timestamp"]}}}},"403":{"description":"API key lacks the deploy scope","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.569Z"}},"required":["success","error","timestamp"]}}}},"404":{"description":"Pod not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.569Z"}},"required":["success","error","timestamp"]}}}}}}},"/jobs":{"get":{"summary":"List jobs","description":"Jobs owned by the current team. Pass ?shape=batch or ?shape=service to filter.","tags":["Jobs"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","enum":["batch","service"]},"required":false,"name":"shape","in":"query"}],"responses":{"200":{"description":"Jobs retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"nullable":true}},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.594Z"}},"required":["success","data","timestamp"]}}}},"400":{"description":"Invalid query","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.594Z"}},"required":["success","error","timestamp"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.594Z"}},"required":["success","error","timestamp"]}}}}}},"post":{"summary":"Create a job","description":"Creates a job from a snapshot version or an image. A batch job runs once at create time; spending routes need an API key with the deploy or full scope.","tags":["Jobs"],"security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":64},"versionId":{"type":"integer"},"image":{"nullable":true},"secrets":{"type":"array","items":{"type":"string"}},"entrypoint":{"nullable":true},"inputSchema":{"nullable":true},"minInstances":{"type":"integer","minimum":0},"maxInstances":{"type":"integer"},"targetConcurrency":{"type":"integer","minimum":1},"idleSeconds":{"type":"integer","minimum":30},"placementDeadlineSeconds":{"type":"integer","minimum":60},"pinnedDeploymentId":{"type":"integer","minimum":0,"exclusiveMinimum":true},"target":{"oneOf":[{"type":"object","properties":{"mode":{"type":"string","enum":["marketplace"]},"offerId":{"type":"string","minLength":1}},"required":["mode"],"additionalProperties":false},{"type":"object","properties":{"mode":{"type":"string","enum":["team"]}},"required":["mode"],"additionalProperties":false},{"type":"object","properties":{"mode":{"type":"string","enum":["machine"]},"deploymentId":{"type":"integer","minimum":0,"exclusiveMinimum":true}},"required":["mode","deploymentId"],"additionalProperties":false}]},"description":{"type":"string","maxLength":2000},"outputs":{"nullable":true},"hardware":{"nullable":true},"placement":{"nullable":true},"checkpoint":{"nullable":true},"maxRuntimeSeconds":{"type":"integer","minimum":60},"schedule":{"type":"string","minLength":1},"webhookUrl":{"type":"string","format":"uri"},"monthlySpendCapCents":{"type":"integer","minimum":1},"stallQuietSeconds":{"type":"integer","minimum":0,"maximum":86400}},"required":["name"]}}}},"responses":{"201":{"description":"Job created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"nullable":true},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.594Z"}},"required":["success","timestamp"]}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.594Z"}},"required":["success","error","timestamp"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.594Z"}},"required":["success","error","timestamp"]}}}},"403":{"description":"API key lacks the deploy scope","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.594Z"}},"required":["success","error","timestamp"]}}}}}}},"/jobs/{id}/runs":{"post":{"summary":"Start a run of a service job","description":"Queues a run with the given inputs and answers 202. A batch job runs once; use rerun to run it again (409 here).","tags":["Jobs"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"inputs":{"type":"object","additionalProperties":{"nullable":true}}}}}}},"responses":{"202":{"description":"Run accepted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"nullable":true},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.594Z"}},"required":["success","timestamp"]}}}},"400":{"description":"Invalid inputs","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.594Z"}},"required":["success","error","timestamp"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.594Z"}},"required":["success","error","timestamp"]}}}},"404":{"description":"Job not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.594Z"}},"required":["success","error","timestamp"]}}}},"409":{"description":"Job is not accepting runs","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.594Z"}},"required":["success","error","timestamp"]}}}}}}},"/jobs/{id}/runs/{runId}":{"get":{"summary":"Get a run","description":"A run with its attempts, cost and any boxes that failed during placement.","tags":["Jobs"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string"},"required":true,"name":"runId","in":"path"}],"responses":{"200":{"description":"Run retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"nullable":true},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.594Z"}},"required":["success","timestamp"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.594Z"}},"required":["success","error","timestamp"]}}}},"404":{"description":"Run not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.594Z"}},"required":["success","error","timestamp"]}}}}}}},"/jobs/cost-preview":{"get":{"summary":"Price a job before creating it","description":"The hourly price of the cheapest machine matching the card type, from the live marketplace feed. Spends nothing.","tags":["Jobs"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"gpuModels","in":"query"},{"schema":{"type":"integer"},"required":false,"name":"gpuCount","in":"query"},{"schema":{"type":"integer","minimum":10,"maximum":10000},"required":true,"name":"diskGb","in":"query"},{"schema":{"type":"string"},"required":false,"name":"providers","in":"query"},{"schema":{"type":"string"},"required":false,"name":"excludeProviders","in":"query"},{"schema":{"type":"integer","minimum":1},"required":false,"name":"maxPriceCentsPerHour","in":"query"},{"schema":{"type":"string","enum":["cheapest","ordered"]},"required":false,"name":"gpuOrder","in":"query"}],"responses":{"200":{"description":"Cost preview computed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"nullable":true},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.595Z"}},"required":["success","timestamp"]}}}},"400":{"description":"Invalid query","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.595Z"}},"required":["success","error","timestamp"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.595Z"}},"required":["success","error","timestamp"]}}}}}}},"/jobs/hardware-availability":{"get":{"summary":"Live availability by GPU model and count","description":"Per GPU model and count: how many offers and providers are eligible and the lowest price, from the live marketplace feed. Spends nothing.","tags":["Jobs"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":10,"maximum":10000,"default":100},"required":false,"name":"diskGb","in":"query"},{"schema":{"type":"string"},"required":false,"name":"providers","in":"query"},{"schema":{"type":"string"},"required":false,"name":"excludeProviders","in":"query"},{"schema":{"type":"integer","minimum":1},"required":false,"name":"maxPriceCentsPerHour","in":"query"}],"responses":{"200":{"description":"Hardware availability retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"nullable":true},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.595Z"}},"required":["success","timestamp"]}}}},"400":{"description":"Invalid query","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.595Z"}},"required":["success","error","timestamp"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.595Z"}},"required":["success","error","timestamp"]}}}}}}},"/audit-log":{"get":{"summary":"List your team audit log","description":"Newest-first page of mutating actions taken in the team named by the `x-team-id` header. Scoped to that one team; there is no way to read another team log. Page with `cursor`, which is the `nextCursor` from the previous page (null on the last).","tags":["Audit Log"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":200},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"Audit log retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"entries":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"actor_user_id":{"type":"string","nullable":true},"actor_email":{"type":"string"},"actor_name":{"type":"string","nullable":true},"action":{"type":"string"},"target_type":{"type":"string","nullable":true},"target_id":{"type":"string","nullable":true},"metadata":{"nullable":true},"status":{"type":"string"}},"required":["id","created_at","actor_user_id","actor_email","actor_name","action","target_type","target_id","status"]}},"nextCursor":{"type":"string","nullable":true}},"required":["entries","nextCursor"]},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.603Z"}},"required":["success","data","timestamp"]}}}},"400":{"description":"Invalid query parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.603Z"}},"required":["success","error","timestamp"]}}}},"401":{"description":"User must be part of a team","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.603Z"}},"required":["success","error","timestamp"]}}}},"403":{"description":"Access to the specified team is forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.603Z"}},"required":["success","error","timestamp"]}}}}}}},"/feedback":{"post":{"summary":"Submit Feedback","description":"Submit platform feedback. At least one of liked, disliked, or comment must be provided.","tags":["Feedback"],"security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitFeedback"}}}},"responses":{"200":{"description":"Feedback submitted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/FeedbackResponse"},"message":{"type":"string","example":"Operation successful"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.605Z"}},"required":["success","data","timestamp"]}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.606Z"}},"required":["success","error","timestamp"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"},"timestamp":{"type":"string","example":"2026-11-16T23:35:12.606Z"}},"required":["success","error","timestamp"]}}}}}}}}}