{"components":{"schemas":{"CreateInstance":{"properties":{"env":{"additionalProperties":{"type":"string"},"type":"object"},"git":{"properties":{"dockerfile":{"type":"string"},"ref":{"type":"string"},"subdir":{"type":"string"},"url":{"type":"string"}},"type":"object"},"http_port":{"type":"integer"},"image":{"description":"Docker image for an app","type":"string"},"labels":{"additionalProperties":{"type":"string"},"type":"object"},"name":{"type":"string"},"public":{"type":"boolean"},"size":{"description":"nano, micro, small, medium, large, xlarge, or a gpu-* size from /templates","type":"string"},"start_command":{"type":"string"},"subdomain":{"type":"string"},"template":{"description":"VPS template id (see /templates)","type":"string"}},"required":["name"],"type":"object"},"Error":{"properties":{"error":{"properties":{"code":{"type":"string"},"details":{"type":"object"},"hint":{"type":"string"},"message":{"type":"string"}},"type":"object"}},"type":"object"},"Exec":{"properties":{"command":{"description":"Shell string or argv array","oneOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"}]},"cwd":{"type":"string"},"env":{"additionalProperties":{"type":"string"},"type":"object"},"stdin":{"type":"string"},"timeout_seconds":{"maximum":900,"type":"integer"},"user":{"type":"string"}},"required":["command"],"type":"object"},"ExecResult":{"properties":{"duration_ms":{"type":"integer"},"exit_code":{"type":"integer"},"stderr":{"type":"string"},"stdout":{"type":"string"},"timed_out":{"type":"boolean"},"truncated":{"type":"boolean"}},"type":"object"},"GPUWaitlist":{"properties":{"company":{"maxLength":120,"type":"string"},"gpu":{"default":"any","enum":["any","rtx","l40s","a100","h100"],"type":"string"},"gpu_count":{"default":1,"maximum":8,"minimum":1,"type":"integer"},"monthly_budget":{"description":"What you would spend per month, in the plan currency","type":"integer"},"notes":{"maxLength":1000,"type":"string"},"timeframe":{"enum":["now","month","quarter","exploring"],"type":"string"},"use_case":{"enum":["inference","agents","fine-tuning","training","embeddings","media","other"],"type":"string"}},"required":["use_case","timeframe"],"type":"object"},"Instance":{"properties":{"created_at":{"format":"date-time","type":"string"},"desired_state":{"type":"string"},"disk_gb":{"type":"integer"},"env_keys":{"items":{"type":"string"},"type":"array"},"gpu_model":{"type":"string"},"gpus":{"description":"NVIDIA GPUs or MIG slices (gpu-* sizes)","type":"integer"},"http_port":{"type":"integer"},"id":{"type":"string"},"internal_hostname":{"description":"Hostname on your private network","type":"string"},"isolation":{"type":"string"},"kind":{"enum":["vps","app"],"type":"string"},"labels":{"additionalProperties":{"type":"string"},"type":"object"},"memory_mb":{"type":"integer"},"name":{"type":"string"},"public":{"type":"boolean"},"size":{"type":"string"},"slug":{"type":"string"},"source":{"additionalProperties":{"type":"string"},"type":"object"},"start_command":{"type":"string"},"status":{"enum":["provisioning","building","starting","running","stopping","stopped","restarting","error","deleting"],"type":"string"},"status_reason":{"type":"string"},"url":{"description":"Public HTTPS URL","type":"string"},"vcpu":{"type":"number"}},"type":"object"},"UpdateInstance":{"properties":{"git":{"type":"object"},"http_port":{"type":"integer"},"image":{"type":"string"},"labels":{"additionalProperties":{"type":"string"},"type":"object"},"name":{"type":"string"},"public":{"type":"boolean"},"size":{"type":"string"},"start_command":{"type":"string"},"subdomain":{"type":"string"}},"type":"object"}},"securitySchemes":{"bearer":{"description":"Cloud API key (cnc_...)","scheme":"bearer","type":"http"}}},"info":{"description":"Linux VPS and container hosting built for AI agents. Authenticate with `Authorization: Bearer cnc_...` (create keys in the dashboard). Errors are `{\"error\":{\"code\",\"message\",\"hint\"}}`. POST /instances accepts an `Idempotency-Key` header. An MCP server with the same capabilities is at /mcp.","title":"CircuitNotion Cloud API","version":"1.0.0"},"openapi":"3.1.0","paths":{"/events":{"get":{"description":"Requires API key scope `read`.","parameters":[{"description":"Max 200","in":"query","name":"limit","schema":{"type":"integer"}},{"description":"Event id cursor","in":"query","name":"before","schema":{"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Events"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Account activity log"}},"/gpu-waitlist":{"delete":{"description":"Requires API key scope `write`.","responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Left"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Leave the GPU waitlist"},"get":{"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Waitlist"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Your GPU waitlist entry (null when not on it), the accepted values, and whether this server has GPUs"},"put":{"description":"Requires API key scope `write`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GPUWaitlist"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"entry":{"$ref":"#/components/schemas/GPUWaitlist"}},"type":"object"}}},"description":"Entry"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Join the GPU waitlist, or update your entry (keeps your place in line)"}},"/instances":{"get":{"description":"Requires API key scope `read`.","parameters":[{"description":"Filter by status","in":"query","name":"status","schema":{"type":"string"}},{"description":"Filter by label key or key=value","in":"query","name":"label","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"instances":{"items":{"$ref":"#/components/schemas/Instance"},"type":"array"}},"type":"object"}}},"description":"Instances"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"List instances"},"post":{"description":"Requires API key scope `write`.","parameters":[{"description":"Block until the instance settles (running/stopped/error)","in":"query","name":"wait","schema":{"type":"boolean"}},{"description":"Seconds to wait (default 180)","in":"query","name":"wait_timeout","schema":{"type":"integer"}},{"in":"header","name":"Idempotency-Key","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateInstance"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"properties":{"instance":{"$ref":"#/components/schemas/Instance"}},"type":"object"}}},"description":"Created"}},"summary":"Create an instance (VPS from template, or app from image/git)"}},"/instances/{id}":{"delete":{"description":"Requires API key scope `write`.","responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Deleted"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Delete an instance and its data"},"get":{"description":"Requires API key scope `read`.","parameters":[{"description":"Block until the instance settles (running/stopped/error)","in":"query","name":"wait","schema":{"type":"boolean"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"instance":{"$ref":"#/components/schemas/Instance"}},"type":"object"}}},"description":"Instance"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Get an instance"},"parameters":[{"description":"Instance id, slug or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"patch":{"description":"Requires API key scope `write`.","parameters":[{"description":"Block until the instance settles (running/stopped/error)","in":"query","name":"wait","schema":{"type":"boolean"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateInstance"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"instance":{"$ref":"#/components/schemas/Instance"}},"type":"object"}}},"description":"Instance"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Update settings (restarts/redeploys when needed)"}},"/instances/{id}/archive":{"get":{"description":"Requires API key scope `files`.","responses":{"200":{"description":"tar.gz"}},"summary":"Download a path as tar.gz"},"parameters":[{"description":"Instance id, slug or name","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Directory (default /app)","in":"query","name":"path","schema":{"type":"string"}}],"put":{"description":"Requires API key scope `files`.","requestBody":{"content":{"application/gzip":{"schema":{"format":"binary","type":"string"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Extracted"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Upload a tar or tar.gz and extract it"}},"/instances/{id}/builds":{"get":{"description":"Requires API key scope `read`.","responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Builds"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Git builds"},"parameters":[{"description":"Instance id, slug or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}]},"/instances/{id}/env":{"get":{"description":"Requires API key scope `read`.","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"env":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"}}},"description":"Env"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Get environment variables"},"parameters":[{"description":"Instance id, slug or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"patch":{"description":"Requires API key scope `write`.","requestBody":{"content":{"application/json":{"schema":{"properties":{"apply":{"type":"boolean"},"set":{"additionalProperties":{"type":"string"},"type":"object"},"unset":{"items":{"type":"string"},"type":"array"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Env"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Set/unset variables"},"put":{"description":"Requires API key scope `write`.","requestBody":{"content":{"application/json":{"schema":{"properties":{"apply":{"type":"boolean"},"env":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Env"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Replace environment"}},"/instances/{id}/events":{"get":{"description":"Requires API key scope `read`.","responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Events"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Activity for this instance"},"parameters":[{"description":"Instance id, slug or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}]},"/instances/{id}/exec":{"parameters":[{"description":"Instance id, slug or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"post":{"description":"Requires API key scope `exec`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Exec"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExecResult"}}},"description":"Result"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Run a command and wait for it"}},"/instances/{id}/files":{"delete":{"description":"Requires API key scope `files`.","responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Deleted"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Delete a file or directory"},"get":{"description":"Requires API key scope `files`.","parameters":[{"description":"Return raw bytes","in":"query","name":"raw","schema":{"type":"boolean"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"File"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Read a file (or list a directory); ?raw=true for bytes"},"parameters":[{"description":"Instance id, slug or name","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"in":"query","name":"path","required":true,"schema":{"type":"string"}}],"put":{"description":"Requires API key scope `files`.","requestBody":{"content":{"application/json":{"schema":{"properties":{"content":{"type":"string"},"encoding":{"enum":["utf-8","base64"],"type":"string"},"mode":{"type":"string"}},"type":"object"}},"application/octet-stream":{"schema":{"format":"binary","type":"string"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Written"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Write a file (raw body, or JSON {content, encoding, mode})"}},"/instances/{id}/logs":{"get":{"description":"Requires API key scope `read`.","parameters":[{"description":"Lines (default 200)","in":"query","name":"tail","schema":{"type":"integer"}},{"description":"10m, 2h, RFC3339 or unix","in":"query","name":"since","schema":{"type":"string"}},{"description":"Stream","in":"query","name":"follow","schema":{"type":"boolean"}},{"description":"text","in":"query","name":"format","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Lines"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Logs (JSON; ?follow=true streams Server-Sent Events; ?format=text)"},"parameters":[{"description":"Instance id, slug or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}]},"/instances/{id}/metrics":{"get":{"description":"Requires API key scope `read`.","responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Metrics"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"CPU/memory/network now"},"parameters":[{"description":"Instance id, slug or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}]},"/instances/{id}/redeploy":{"parameters":[{"description":"Instance id, slug or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"post":{"description":"Requires API key scope `write`.","parameters":[{"description":"Block until the instance settles (running/stopped/error)","in":"query","name":"wait","schema":{"type":"boolean"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"instance":{"$ref":"#/components/schemas/Instance"}},"type":"object"}}},"description":"Instance"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Recreate from source (re-pull or rebuild)"}},"/instances/{id}/restart":{"parameters":[{"description":"Instance id, slug or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"post":{"description":"Requires API key scope `write`.","parameters":[{"description":"Block until the instance settles (running/stopped/error)","in":"query","name":"wait","schema":{"type":"boolean"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"instance":{"$ref":"#/components/schemas/Instance"}},"type":"object"}}},"description":"Instance"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Restart"}},"/instances/{id}/start":{"parameters":[{"description":"Instance id, slug or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"post":{"description":"Requires API key scope `write`.","parameters":[{"description":"Block until the instance settles (running/stopped/error)","in":"query","name":"wait","schema":{"type":"boolean"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"instance":{"$ref":"#/components/schemas/Instance"}},"type":"object"}}},"description":"Instance"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Start"}},"/instances/{id}/stop":{"parameters":[{"description":"Instance id, slug or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"post":{"description":"Requires API key scope `write`.","parameters":[{"description":"Block until the instance settles (running/stopped/error)","in":"query","name":"wait","schema":{"type":"boolean"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"instance":{"$ref":"#/components/schemas/Instance"}},"type":"object"}}},"description":"Instance"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Stop"}},"/instances/{id}/terminal":{"get":{"description":"Requires API key scope `exec`.","parameters":[{"description":"Rows","in":"query","name":"rows","schema":{"type":"integer"}},{"description":"Columns","in":"query","name":"cols","schema":{"type":"integer"}}],"responses":{"101":{"description":"WebSocket"}},"summary":"Interactive TTY over WebSocket"},"parameters":[{"description":"Instance id, slug or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}]},"/instances/{id}/usage":{"get":{"description":"Requires API key scope `read`.","parameters":[{"description":"Days (default 30)","in":"query","name":"days","schema":{"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Usage"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Daily public traffic and disk"},"parameters":[{"description":"Instance id, slug or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}]},"/me":{"get":{"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Account"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Current account, plan limits and usage"}},"/plans":{"get":{"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Plans"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Plans and prices (30-day periods)"}},"/templates":{"get":{"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Catalog"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"VPS templates and instance sizes"}}},"security":[{"bearer":[]}],"servers":[{"url":"https://cloud.circuitnotion.com/api/v1"}]}