{"components":{"securitySchemes":{"bearerAuth":{"scheme":"bearer","type":"http"}}},"info":{"title":"Treliso customer API","version":"0.1.0"},"openapi":"3.1.0","paths":{"/api/accounts":{"get":{"description":"List accounts the customer belongs to, including their role.","operationId":"list_accounts","parameters":[],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"items":{"items":{"properties":{"id":{"format":"uuid","type":"string"},"name":{"type":"string"},"role":{"type":"string"}},"required":["id","name","role"],"type":"object"},"type":"array"}},"required":["items"],"type":"object"}}},"description":"Success"},"400":{"description":"Invalid arguments"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope or resource permission"},"404":{"description":"Resource not found"},"409":{"description":"Plan allowance or resource capacity exceeded"}},"security":[{"bearerAuth":[]}],"x-required-scope":"read"},"post":{"description":"Create an account owned by the authenticated customer.","operationId":"create_account","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"name":{"maxLength":100,"minLength":1,"type":"string"}},"required":["name"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"account_id":{"format":"uuid","type":"string"}},"required":["account_id"],"type":"object"}}},"description":"Success"},"400":{"description":"Invalid arguments"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope or resource permission"},"404":{"description":"Resource not found"},"409":{"description":"Plan allowance or resource capacity exceeded"}},"security":[{"bearerAuth":[]}],"x-required-scope":"manage"}},"/api/accounts/{account_id}/backups":{"get":{"description":"List account recovery points and VM backup freshness; account administration required. Retained backups remain accessible after VM deletion.","operationId":"list_backups","parameters":[{"in":"path","name":"account_id","required":true,"schema":{"format":"uuid","type":"string"}},{"in":"query","name":"limit","required":false,"schema":{"default":100,"format":"int32","maximum":1000,"minimum":1,"type":["integer","null"]}},{"in":"query","name":"vm_id","required":false,"schema":{"format":"uuid","type":["string","null"]}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"coverage":{"properties":{"freshness":{"additionalProperties":{"format":"int64","minimum":0,"type":"integer"},"propertyNames":{"type":"string"},"type":"object"},"oldest_recovery_point_age_seconds":{"format":"int64","minimum":0,"type":["integer","null"]},"vm_count":{"format":"int64","minimum":0,"type":"integer"}},"required":["vm_count","freshness"],"type":"object"},"items":{"items":{"properties":{"account_id":{"format":"uuid","type":"string"},"age_seconds":{"format":"int64","minimum":0,"type":["integer","null"]},"captured_at_ms":{"format":"int64","type":"integer"},"disk_bytes":{"format":"int64","minimum":0,"type":"integer"},"disk_sha256":{"type":["string","null"]},"error":{"type":["string","null"]},"expired_at_ms":{"format":"int64","type":["integer","null"]},"expiry_started_at_ms":{"format":"int64","type":["integer","null"]},"generation":{"format":"int64","minimum":0,"type":"integer"},"id":{"format":"uuid","type":"string"},"manifest_sha256":{"type":["string","null"]},"manifest_version":{"format":"int32","minimum":0,"type":"integer"},"memory_mib":{"format":"int64","minimum":0,"type":"integer"},"repository_id":{"type":"string"},"snapshot_id":{"type":["string","null"]},"source_allocation_id":{"format":"uuid","type":["string","null"]},"source_host_id":{"format":"uuid","type":"string"},"source_name":{"type":"string"},"source_pool_id":{"format":"uuid","type":["string","null"]},"state":{"type":"string"},"storage_gib":{"format":"int64","minimum":0,"type":"integer"},"uploaded_at_ms":{"format":"int64","type":["integer","null"]},"vm_id":{"format":"uuid","type":"string"}},"required":["id","account_id","vm_id","source_host_id","source_name","memory_mib","storage_gib","disk_bytes","captured_at_ms","repository_id","manifest_version","generation","state"],"type":"object"},"type":"array"}},"required":["items","coverage"],"type":"object"}}},"description":"Success"},"400":{"description":"Invalid arguments"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope or resource permission"},"404":{"description":"Resource not found"},"409":{"description":"Plan allowance or resource capacity exceeded"}},"security":[{"bearerAuth":[]}],"x-required-scope":"read"}},"/api/accounts/{id}/email":{"get":{"description":"Get an account mailbox; owners and administrators only.","operationId":"get_account_mailbox","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"account_id":{"format":"uuid","type":"string"},"address":{"type":"string"},"created_at":{"format":"int64","type":"integer"},"enabled":{"type":"boolean"},"id":{"format":"uuid","type":"string"},"vm_id":{"format":"uuid","type":["string","null"]}},"required":["id","account_id","address","enabled","created_at"],"type":"object"}}},"description":"Success"},"400":{"description":"Invalid arguments"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope or resource permission"},"404":{"description":"Resource not found"},"409":{"description":"Plan allowance or resource capacity exceeded"}},"security":[{"bearerAuth":[]}],"x-required-scope":"email_read"}},"/api/accounts/{id}/members":{"post":{"description":"Add or update an account member; owners and administrators only.","operationId":"add_member","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"role":{"enum":["admin","member"],"type":"string"},"user_id":{"format":"uuid","type":"string"}},"required":["role","user_id"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"ok":{"type":"boolean"}},"required":["ok"],"type":"object"}}},"description":"Success"},"400":{"description":"Invalid arguments"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope or resource permission"},"404":{"description":"Resource not found"},"409":{"description":"Plan allowance or resource capacity exceeded"}},"security":[{"bearerAuth":[]}],"x-required-scope":"manage"}},"/api/accounts/{id}/members/{user}":{"delete":{"description":"Remove an account member and their VM grants; account owners cannot be removed.","operationId":"remove_member","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}},{"in":"path","name":"user","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"ok":{"type":"boolean"}},"required":["ok"],"type":"object"}}},"description":"Success"},"400":{"description":"Invalid arguments"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope or resource permission"},"404":{"description":"Resource not found"},"409":{"description":"Plan allowance or resource capacity exceeded"}},"security":[{"bearerAuth":[]}],"x-required-scope":"manage"}},"/api/backups/{id}":{"get":{"description":"Inspect an account-owned disk recovery point; account administration required.","operationId":"get_backup","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"account_id":{"format":"uuid","type":"string"},"age_seconds":{"format":"int64","minimum":0,"type":["integer","null"]},"captured_at_ms":{"format":"int64","type":"integer"},"disk_bytes":{"format":"int64","minimum":0,"type":"integer"},"disk_sha256":{"type":["string","null"]},"error":{"type":["string","null"]},"expired_at_ms":{"format":"int64","type":["integer","null"]},"expiry_started_at_ms":{"format":"int64","type":["integer","null"]},"generation":{"format":"int64","minimum":0,"type":"integer"},"id":{"format":"uuid","type":"string"},"manifest_sha256":{"type":["string","null"]},"manifest_version":{"format":"int32","minimum":0,"type":"integer"},"memory_mib":{"format":"int64","minimum":0,"type":"integer"},"repository_id":{"type":"string"},"snapshot_id":{"type":["string","null"]},"source_allocation_id":{"format":"uuid","type":["string","null"]},"source_host_id":{"format":"uuid","type":"string"},"source_name":{"type":"string"},"source_pool_id":{"format":"uuid","type":["string","null"]},"state":{"type":"string"},"storage_gib":{"format":"int64","minimum":0,"type":"integer"},"uploaded_at_ms":{"format":"int64","type":["integer","null"]},"vm_id":{"format":"uuid","type":"string"}},"required":["id","account_id","vm_id","source_host_id","source_name","memory_mib","storage_gib","disk_bytes","captured_at_ms","repository_id","manifest_version","generation","state"],"type":"object"}}},"description":"Success"},"400":{"description":"Invalid arguments"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope or resource permission"},"404":{"description":"Resource not found"},"409":{"description":"Plan allowance or resource capacity exceeded"}},"security":[{"bearerAuth":[]}],"x-required-scope":"read"}},"/api/backups/{id}/restore":{"post":{"description":"Import a disk recovery point into a new, stopped VM in an eligible pool. Requires account administration. Inspect the imported disk before explicitly starting customer workloads.","operationId":"restore_backup","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}},{"in":"header","name":"Idempotency-Key","required":false,"schema":{"maxLength":128,"minLength":1,"type":["string","null"]}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"pool_id":{"format":"uuid","type":"string"}},"required":["pool_id"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"operation_id":{"format":"uuid","type":"string"},"source_backup_id":{"format":"uuid","type":"string"},"vm":{"properties":{"account_id":{"format":"uuid","type":"string"},"desired":{"type":"boolean"},"host_id":{"format":"uuid","type":"string"},"id":{"format":"uuid","type":"string"},"memory_mib":{"format":"int64","minimum":0,"type":"integer"},"name":{"type":"string"},"pool_id":{"format":"uuid","type":["string","null"]},"slot_id":{"format":"uuid","type":"string"},"state":{"type":"string"},"storage_gib":{"format":"int64","minimum":0,"type":"integer"}},"required":["id","account_id","name","slot_id","host_id","memory_mib","storage_gib","desired","state"],"type":"object"}},"required":["vm","operation_id","source_backup_id"],"type":"object"}}},"description":"Success"},"400":{"description":"Invalid arguments"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope or resource permission"},"404":{"description":"Resource not found"},"409":{"description":"Plan allowance or resource capacity exceeded"}},"security":[{"bearerAuth":[]}],"x-required-scope":"manage"}},"/api/mailboxes/{id}/messages":{"get":{"description":"List a mailbox's newest messages with cursor pagination; limit defaults to 50, maximum 100.","operationId":"list_email_messages","parameters":[{"in":"query","name":"before","required":false,"schema":{"format":"uuid","type":["string","null"]}},{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}},{"in":"query","name":"limit","required":false,"schema":{"default":50,"format":"int32","maximum":100,"minimum":1,"type":["integer","null"]}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"messages":{"items":{"properties":{"attachment_count":{"format":"int32","minimum":0,"type":"integer"},"created_at":{"format":"int64","type":"integer"},"direction":{"enum":["inbound","outbound"],"type":"string"},"from":{"type":"string"},"id":{"format":"uuid","type":"string"},"mailbox_id":{"format":"uuid","type":"string"},"read_at":{"format":"int64","type":["integer","null"]},"status":{"enum":["received","queued","sending","accepted","delivered","uncertain","failed","bounced"],"type":"string"},"subject":{"type":"string"},"to":{"type":"string"}},"required":["id","mailbox_id","direction","status","from","to","subject","created_at","attachment_count"],"type":"object"},"type":"array"},"next_before":{"format":"uuid","type":["string","null"]}},"required":["messages"],"type":"object"}}},"description":"Success"},"400":{"description":"Invalid arguments"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope or resource permission"},"404":{"description":"Resource not found"},"409":{"description":"Plan allowance or resource capacity exceeded"}},"security":[{"bearerAuth":[]}],"x-required-scope":"email_read"},"post":{"description":"Queue an email from the owned mailbox. Idempotency-Key is required; identical retries return the same message.","operationId":"send_email","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}},{"in":"header","name":"Idempotency-Key","required":true,"schema":{"maxLength":128,"minLength":1,"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"attachments":{"items":{"additionalProperties":false,"properties":{"content":{"contentEncoding":"base64","maxLength":2796204,"type":"string"},"filename":{"maxLength":255,"minLength":1,"type":"string"},"type":{"maxLength":127,"type":"string"}},"required":["filename","content","type"],"type":"object"},"maxItems":10,"type":"array"},"reply_to_message_id":{"format":"uuid","type":["string","null"]},"subject":{"maxLength":998,"type":"string"},"text":{"maxLength":262144,"minLength":1,"type":"string"},"to":{"format":"email","maxLength":254,"type":"string"}},"required":["subject","text","to"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"attachment_count":{"format":"int32","minimum":0,"type":"integer"},"attachments":{"items":{"properties":{"filename":{"type":"string"},"id":{"format":"uuid","type":"string"},"size":{"format":"int64","minimum":0,"type":"integer"},"type":{"type":"string"}},"required":["id","filename","type","size"],"type":"object"},"type":"array"},"created_at":{"format":"int64","type":"integer"},"direction":{"enum":["inbound","outbound"],"type":"string"},"error":{"type":["string","null"]},"from":{"type":"string"},"id":{"format":"uuid","type":"string"},"mailbox_id":{"format":"uuid","type":"string"},"provider_message_id":{"type":["string","null"]},"read_at":{"format":"int64","type":["integer","null"]},"reply_to_address":{"type":["string","null"]},"reply_to_message_id":{"format":"uuid","type":["string","null"]},"status":{"enum":["received","queued","sending","accepted","delivered","uncertain","failed","bounced"],"type":"string"},"subject":{"type":"string"},"text":{"type":"string"},"to":{"type":"string"}},"required":["id","mailbox_id","direction","status","from","to","subject","created_at","attachment_count","text","attachments"],"type":"object"}}},"description":"Success"},"400":{"description":"Invalid arguments"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope or resource permission"},"404":{"description":"Resource not found"},"409":{"description":"Plan allowance or resource capacity exceeded"}},"security":[{"bearerAuth":[]}],"x-required-scope":"email_send"}},"/api/mailboxes/{id}/messages/{message_id}":{"get":{"description":"Read a text email and its attachment metadata.","operationId":"get_email_message","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}},{"in":"path","name":"message_id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"attachment_count":{"format":"int32","minimum":0,"type":"integer"},"attachments":{"items":{"properties":{"filename":{"type":"string"},"id":{"format":"uuid","type":"string"},"size":{"format":"int64","minimum":0,"type":"integer"},"type":{"type":"string"}},"required":["id","filename","type","size"],"type":"object"},"type":"array"},"created_at":{"format":"int64","type":"integer"},"direction":{"enum":["inbound","outbound"],"type":"string"},"error":{"type":["string","null"]},"from":{"type":"string"},"id":{"format":"uuid","type":"string"},"mailbox_id":{"format":"uuid","type":"string"},"provider_message_id":{"type":["string","null"]},"read_at":{"format":"int64","type":["integer","null"]},"reply_to_address":{"type":["string","null"]},"reply_to_message_id":{"format":"uuid","type":["string","null"]},"status":{"enum":["received","queued","sending","accepted","delivered","uncertain","failed","bounced"],"type":"string"},"subject":{"type":"string"},"text":{"type":"string"},"to":{"type":"string"}},"required":["id","mailbox_id","direction","status","from","to","subject","created_at","attachment_count","text","attachments"],"type":"object"}}},"description":"Success"},"400":{"description":"Invalid arguments"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope or resource permission"},"404":{"description":"Resource not found"},"409":{"description":"Plan allowance or resource capacity exceeded"}},"security":[{"bearerAuth":[]}],"x-required-scope":"email_read"}},"/api/mailboxes/{id}/messages/{message_id}/attachments/{attachment_id}":{"get":{"description":"Download an email attachment as base64.","operationId":"get_email_attachment","parameters":[{"in":"path","name":"attachment_id","required":true,"schema":{"format":"uuid","type":"string"}},{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}},{"in":"path","name":"message_id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"content":{"type":"string"},"filename":{"type":"string"},"id":{"format":"uuid","type":"string"},"size":{"format":"int64","minimum":0,"type":"integer"},"type":{"type":"string"}},"required":["id","filename","type","size","content"],"type":"object"}}},"description":"Success"},"400":{"description":"Invalid arguments"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope or resource permission"},"404":{"description":"Resource not found"},"409":{"description":"Plan allowance or resource capacity exceeded"}},"security":[{"bearerAuth":[]}],"x-required-scope":"email_read"}},"/api/operations/{id}":{"get":{"description":"Inspect an asynchronous VM lifecycle operation.","operationId":"get_operation","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"attempts":{"format":"int32","type":"integer"},"error":{"type":["string","null"]},"id":{"format":"uuid","type":"string"},"kind":{"type":"string"},"state":{"type":"string"},"vm_id":{"format":"uuid","type":"string"}},"required":["id","vm_id","kind","state","attempts"],"type":"object"}}},"description":"Success"},"400":{"description":"Invalid arguments"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope or resource permission"},"404":{"description":"Resource not found"},"409":{"description":"Plan allowance or resource capacity exceeded"}},"security":[{"bearerAuth":[]}],"x-required-scope":"read"}},"/api/pool-options":{"get":{"description":"List configured purchased plan allowances and reservable hosts by region for an account.","operationId":"list_pool_options","parameters":[{"in":"query","name":"account_id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"hosts":{"items":{"properties":{"available_cpu_millis":{"format":"int32","minimum":0,"type":"integer"},"available_memory_mib":{"format":"int64","minimum":0,"type":"integer"},"available_storage_gib":{"format":"int64","minimum":0,"type":"integer"},"cpu_millis":{"format":"int32","minimum":0,"type":"integer"},"id":{"format":"uuid","type":"string"},"memory_mib":{"format":"int64","minimum":0,"type":"integer"},"region":{"type":"string"},"storage_gib":{"format":"int64","minimum":0,"type":"integer"}},"required":["id","region","cpu_millis","memory_mib","storage_gib","available_cpu_millis","available_memory_mib","available_storage_gib"],"type":"object"},"type":"array"},"plans":{"items":{"properties":{"cpu_millis":{"format":"int32","minimum":0,"type":"integer"},"id":{"type":"string"},"memory_mib":{"format":"int64","minimum":0,"type":"integer"},"name":{"type":"string"},"quantity":{"format":"int32","minimum":0,"type":"integer"},"storage_gib":{"format":"int64","minimum":0,"type":"integer"},"used":{"format":"int32","minimum":0,"type":"integer"},"vm_cap":{"format":"int32","minimum":0,"type":"integer"}},"required":["id","name","cpu_millis","memory_mib","storage_gib","vm_cap","quantity","used"],"type":"object"},"type":"array"}},"required":["plans","hosts"],"type":"object"}}},"description":"Success"},"400":{"description":"Invalid arguments"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope or resource permission"},"404":{"description":"Resource not found"},"409":{"description":"Plan allowance or resource capacity exceeded"}},"security":[{"bearerAuth":[]}],"x-required-scope":"read"}},"/api/pools":{"get":{"description":"List account pools and reserved VM memory, disk capacity and VM count. Stopped VMs retain their reservations.","operationId":"list_pools","parameters":[],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"items":{"items":{"properties":{"account_id":{"format":"uuid","type":"string"},"cpu_millis":{"format":"int32","minimum":0,"type":"integer"},"host_id":{"format":"uuid","type":"string"},"id":{"format":"uuid","type":"string"},"memory_mib":{"format":"int64","minimum":0,"type":"integer"},"name":{"type":"string"},"plan_id":{"type":"string"},"region":{"type":"string"},"state":{"type":"string"},"storage_gib":{"format":"int64","minimum":0,"type":"integer"},"usage":{"properties":{"memory_mib":{"format":"int64","minimum":0,"type":"integer"},"storage_gib":{"format":"int64","minimum":0,"type":"integer"},"vm_count":{"format":"int32","minimum":0,"type":"integer"}},"required":["memory_mib","storage_gib","vm_count"],"type":"object"},"vm_cap":{"format":"int32","minimum":0,"type":"integer"}},"required":["id","account_id","name","plan_id","region","host_id","cpu_millis","memory_mib","storage_gib","vm_cap","state","usage"],"type":"object"},"type":"array"}},"required":["items"],"type":"object"}}},"description":"Success"},"400":{"description":"Invalid arguments"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope or resource permission"},"404":{"description":"Resource not found"},"409":{"description":"Plan allowance or resource capacity exceeded"}},"security":[{"bearerAuth":[]}],"x-required-scope":"read"},"post":{"description":"Reserve purchased plan capacity on one host in the selected region. CPU time is shared by all pool VMs.","operationId":"create_pool","parameters":[{"in":"header","name":"Idempotency-Key","required":false,"schema":{"maxLength":128,"minLength":1,"type":["string","null"]}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"account_id":{"format":"uuid","type":"string"},"host_id":{"format":"uuid","type":["string","null"]},"name":{"maxLength":100,"minLength":1,"type":"string"},"plan_id":{"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","type":"string"},"region":{"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","type":"string"}},"required":["account_id","name","plan_id","region"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"pool":{"properties":{"account_id":{"format":"uuid","type":"string"},"cpu_millis":{"format":"int32","minimum":0,"type":"integer"},"host_id":{"format":"uuid","type":"string"},"id":{"format":"uuid","type":"string"},"memory_mib":{"format":"int64","minimum":0,"type":"integer"},"name":{"type":"string"},"plan_id":{"type":"string"},"region":{"type":"string"},"state":{"type":"string"},"storage_gib":{"format":"int64","minimum":0,"type":"integer"},"usage":{"properties":{"memory_mib":{"format":"int64","minimum":0,"type":"integer"},"storage_gib":{"format":"int64","minimum":0,"type":"integer"},"vm_count":{"format":"int32","minimum":0,"type":"integer"}},"required":["memory_mib","storage_gib","vm_count"],"type":"object"},"vm_cap":{"format":"int32","minimum":0,"type":"integer"}},"required":["id","account_id","name","plan_id","region","host_id","cpu_millis","memory_mib","storage_gib","vm_cap","state","usage"],"type":"object"}},"required":["pool"],"type":"object"}}},"description":"Success"},"400":{"description":"Invalid arguments"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope or resource permission"},"404":{"description":"Resource not found"},"409":{"description":"Plan allowance or resource capacity exceeded"}},"security":[{"bearerAuth":[]}],"x-required-scope":"manage"}},"/api/pools/{id}":{"delete":{"description":"Release an empty pool. All VM deletions must have completed first.","operationId":"delete_pool","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"ok":{"type":"boolean"}},"required":["ok"],"type":"object"}}},"description":"Success"},"400":{"description":"Invalid arguments"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope or resource permission"},"404":{"description":"Resource not found"},"409":{"description":"Plan allowance or resource capacity exceeded"}},"security":[{"bearerAuth":[]}],"x-required-scope":"manage"},"get":{"description":"Inspect an account pool, its immutable placement and current reservations.","operationId":"get_pool","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"account_id":{"format":"uuid","type":"string"},"cpu_millis":{"format":"int32","minimum":0,"type":"integer"},"host_id":{"format":"uuid","type":"string"},"id":{"format":"uuid","type":"string"},"memory_mib":{"format":"int64","minimum":0,"type":"integer"},"name":{"type":"string"},"plan_id":{"type":"string"},"region":{"type":"string"},"state":{"type":"string"},"storage_gib":{"format":"int64","minimum":0,"type":"integer"},"usage":{"properties":{"memory_mib":{"format":"int64","minimum":0,"type":"integer"},"storage_gib":{"format":"int64","minimum":0,"type":"integer"},"vm_count":{"format":"int32","minimum":0,"type":"integer"}},"required":["memory_mib","storage_gib","vm_count"],"type":"object"},"vm_cap":{"format":"int32","minimum":0,"type":"integer"}},"required":["id","account_id","name","plan_id","region","host_id","cpu_millis","memory_mib","storage_gib","vm_cap","state","usage"],"type":"object"}}},"description":"Success"},"400":{"description":"Invalid arguments"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope or resource permission"},"404":{"description":"Resource not found"},"409":{"description":"Plan allowance or resource capacity exceeded"}},"security":[{"bearerAuth":[]}],"x-required-scope":"read"}},"/api/ssh-keys/challenges":{"post":{"description":"Request a short-lived challenge to prove ownership of an SSH public key.","operationId":"key_challenge","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"public_key":{"type":"string"}},"required":["public_key"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"challenge":{"type":"string"},"challenge_id":{"format":"uuid","type":"string"},"namespace":{"type":"string"}},"required":["challenge_id","challenge","namespace"],"type":"object"}}},"description":"Success"},"400":{"description":"Invalid arguments"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope or resource permission"},"404":{"description":"Resource not found"},"409":{"description":"Plan allowance or resource capacity exceeded"}},"security":[{"bearerAuth":[]}],"x-required-scope":"manage"}},"/api/ssh-keys/challenges/{id}":{"post":{"description":"Enroll an SSH key using its signed challenge; each challenge may be used once.","operationId":"enroll_key","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"signature":{"type":"string"}},"required":["signature"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"fingerprint":{"type":"string"},"key_id":{"format":"uuid","type":"string"}},"required":["key_id","fingerprint"],"type":"object"}}},"description":"Success"},"400":{"description":"Invalid arguments"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope or resource permission"},"404":{"description":"Resource not found"},"409":{"description":"Plan allowance or resource capacity exceeded"}},"security":[{"bearerAuth":[]}],"x-required-scope":"manage"}},"/api/ssh-keys/{id}":{"delete":{"description":"Revoke one of the customer's SSH keys.","operationId":"revoke_key","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"ok":{"type":"boolean"}},"required":["ok"],"type":"object"}}},"description":"Success"},"400":{"description":"Invalid arguments"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope or resource permission"},"404":{"description":"Resource not found"},"409":{"description":"Plan allowance or resource capacity exceeded"}},"security":[{"bearerAuth":[]}],"x-required-scope":"manage"}},"/api/vms":{"get":{"description":"List the VMs accessible through account roles or explicit VM grants.","operationId":"list_vms","parameters":[],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"items":{"items":{"properties":{"account_id":{"format":"uuid","type":"string"},"desired":{"type":"boolean"},"host_id":{"format":"uuid","type":"string"},"id":{"format":"uuid","type":"string"},"memory_mib":{"format":"int64","minimum":0,"type":"integer"},"name":{"type":"string"},"pool_id":{"format":"uuid","type":["string","null"]},"slot_id":{"format":"uuid","type":"string"},"state":{"type":"string"},"storage_gib":{"format":"int64","minimum":0,"type":"integer"}},"required":["id","account_id","name","slot_id","host_id","memory_mib","storage_gib","desired","state"],"type":"object"},"type":"array"}},"required":["items"],"type":"object"}}},"description":"Success"},"400":{"description":"Invalid arguments"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope or resource permission"},"404":{"description":"Resource not found"},"409":{"description":"Plan allowance or resource capacity exceeded"}},"security":[{"bearerAuth":[]}],"x-required-scope":"read"},"post":{"description":"Provision a VM in a pool with a generated name and reserved memory/disk capacity; poll get_operation for readiness. Pool CPU time is shared.","operationId":"create_vm","parameters":[{"in":"header","name":"Idempotency-Key","required":false,"schema":{"maxLength":128,"minLength":1,"type":["string","null"]}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"account_id":{"format":"uuid","type":"string"},"memory_mib":{"default":256,"format":"int64","maximum":1048576,"minimum":128,"type":["integer","null"]},"pool_id":{"format":"uuid","type":"string"},"storage_gib":{"default":4,"format":"int64","maximum":1048576,"minimum":4,"type":["integer","null"]}},"required":["account_id","pool_id"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"operation_id":{"format":"uuid","type":"string"},"vm":{"properties":{"account_id":{"format":"uuid","type":"string"},"desired":{"type":"boolean"},"host_id":{"format":"uuid","type":"string"},"id":{"format":"uuid","type":"string"},"memory_mib":{"format":"int64","minimum":0,"type":"integer"},"name":{"type":"string"},"pool_id":{"format":"uuid","type":["string","null"]},"slot_id":{"format":"uuid","type":"string"},"state":{"type":"string"},"storage_gib":{"format":"int64","minimum":0,"type":"integer"}},"required":["id","account_id","name","slot_id","host_id","memory_mib","storage_gib","desired","state"],"type":"object"}},"required":["vm","operation_id"],"type":"object"}}},"description":"Success"},"400":{"description":"Invalid arguments"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope or resource permission"},"404":{"description":"Resource not found"},"409":{"description":"Plan allowance or resource capacity exceeded"}},"security":[{"bearerAuth":[]}],"x-required-scope":"manage"}},"/api/vms/{id}":{"delete":{"description":"Delete a VM and retire its public domains and TCP routes.","operationId":"delete_vm","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"operation_id":{"format":"uuid","type":"string"}},"required":["operation_id"],"type":"object"}}},"description":"Success"},"400":{"description":"Invalid arguments"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope or resource permission"},"404":{"description":"Resource not found"},"409":{"description":"Plan allowance or resource capacity exceeded"}},"security":[{"bearerAuth":[]}],"x-required-scope":"manage"},"get":{"description":"Inspect an accessible VM and its lifecycle state.","operationId":"get_vm","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"account_id":{"format":"uuid","type":"string"},"desired":{"type":"boolean"},"host_id":{"format":"uuid","type":"string"},"id":{"format":"uuid","type":"string"},"memory_mib":{"format":"int64","minimum":0,"type":"integer"},"name":{"type":"string"},"pool_id":{"format":"uuid","type":["string","null"]},"slot_id":{"format":"uuid","type":"string"},"state":{"type":"string"},"storage_gib":{"format":"int64","minimum":0,"type":"integer"}},"required":["id","account_id","name","slot_id","host_id","memory_mib","storage_gib","desired","state"],"type":"object"}}},"description":"Success"},"400":{"description":"Invalid arguments"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope or resource permission"},"404":{"description":"Resource not found"},"409":{"description":"Plan allowance or resource capacity exceeded"}},"security":[{"bearerAuth":[]}],"x-required-scope":"read"}},"/api/vms/{id}/deployments":{"get":{"description":"List managed applications inside a VM.","operationId":"list_deployments","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"items":{"items":{"properties":{"command":{"type":"string"},"directory":{"type":"string"},"id":{"format":"uuid","type":"string"},"last_exit_code":{"format":"int32","type":["integer","null"]},"name":{"type":"string"},"pid":{"format":"int32","minimum":0,"type":["integer","null"]},"restarts":{"format":"int32","minimum":0,"type":"integer"},"status":{"type":"string"}},"required":["id","name","directory","command","status","restarts"],"type":"object"},"type":"array"}},"required":["items"],"type":"object"}}},"description":"Success"},"400":{"description":"Invalid arguments"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope or resource permission"},"404":{"description":"Resource not found"},"409":{"description":"Plan allowance or resource capacity exceeded"}},"security":[{"bearerAuth":[]}],"x-required-scope":"vm_access"}},"/api/vms/{id}/deployments/{deployment}":{"get":{"description":"Inspect a managed application's command, supervisor state and restart count.","operationId":"get_deployment","parameters":[{"in":"path","name":"deployment","required":false,"schema":{"default":"app","pattern":"^[a-zA-Z0-9_-]{1,64}$","type":"string"}},{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"command":{"type":"string"},"directory":{"type":"string"},"id":{"format":"uuid","type":"string"},"last_exit_code":{"format":"int32","type":["integer","null"]},"name":{"type":"string"},"pid":{"format":"int32","minimum":0,"type":["integer","null"]},"restarts":{"format":"int32","minimum":0,"type":"integer"},"status":{"type":"string"}},"required":["id","name","directory","command","status","restarts"],"type":"object"}}},"description":"Success"},"400":{"description":"Invalid arguments"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope or resource permission"},"404":{"description":"Resource not found"},"409":{"description":"Plan allowance or resource capacity exceeded"}},"security":[{"bearerAuth":[]}],"x-required-scope":"vm_access"},"put":{"description":"Replace a named managed application with uploaded files and a start command; it persists across reconnects and guest boots.","operationId":"deploy_app","parameters":[{"in":"path","name":"deployment","required":false,"schema":{"default":"app","pattern":"^[a-zA-Z0-9_-]{1,64}$","type":"string"}},{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}},{"in":"header","name":"Idempotency-Key","required":false,"schema":{"maxLength":128,"minLength":1,"type":["string","null"]}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"command":{"maxLength":4096,"minLength":1,"type":"string"},"cwd":{"maxLength":4096,"minLength":1,"type":["string","null"]},"env":{"additionalProperties":{"maxLength":4096,"type":"string"},"maxProperties":64,"propertyNames":{"maxLength":128,"minLength":1},"type":["object","null"]}},"required":["command"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"command":{"type":"string"},"directory":{"type":"string"},"id":{"format":"uuid","type":"string"},"last_exit_code":{"format":"int32","type":["integer","null"]},"name":{"type":"string"},"pid":{"format":"int32","minimum":0,"type":["integer","null"]},"restarts":{"format":"int32","minimum":0,"type":"integer"},"status":{"type":"string"}},"required":["id","name","directory","command","status","restarts"],"type":"object"}}},"description":"Success"},"400":{"description":"Invalid arguments"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope or resource permission"},"404":{"description":"Resource not found"},"409":{"description":"Plan allowance or resource capacity exceeded"}},"security":[{"bearerAuth":[]}],"x-required-scope":"vm_access"}},"/api/vms/{id}/deployments/{deployment}/logs":{"get":{"description":"Read a bounded range of a managed application's stdout or stderr log; data is base64.","operationId":"deployment_logs","parameters":[{"in":"path","name":"deployment","required":false,"schema":{"default":"app","pattern":"^[a-zA-Z0-9_-]{1,64}$","type":"string"}},{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}},{"in":"query","name":"length","required":false,"schema":{"default":65536,"format":"int32","maximum":262144,"minimum":1,"type":["integer","null"]}},{"in":"query","name":"offset","required":false,"schema":{"format":"int64","minimum":0,"type":["integer","null"]}},{"in":"query","name":"stream","required":false,"schema":{"enum":["stdout","stderr",null],"type":["string","null"]}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"type":"string"},"eof":{"type":"boolean"},"offset":{"format":"int64","minimum":0,"type":"integer"}},"required":["offset","data","eof"],"type":"object"}}},"description":"Success"},"400":{"description":"Invalid arguments"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope or resource permission"},"404":{"description":"Resource not found"},"409":{"description":"Plan allowance or resource capacity exceeded"}},"security":[{"bearerAuth":[]}],"x-required-scope":"vm_access"}},"/api/vms/{id}/deployments/{deployment}/stop":{"post":{"description":"Stop a managed application and disable automatic restarts, including after a guest reboot.","operationId":"stop_deployment","parameters":[{"in":"path","name":"deployment","required":false,"schema":{"default":"app","pattern":"^[a-zA-Z0-9_-]{1,64}$","type":"string"}},{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"ok":{"type":"boolean"}},"required":["ok"],"type":"object"}}},"description":"Success"},"400":{"description":"Invalid arguments"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope or resource permission"},"404":{"description":"Resource not found"},"409":{"description":"Plan allowance or resource capacity exceeded"}},"security":[{"bearerAuth":[]}],"x-required-scope":"vm_access"}},"/api/vms/{id}/domains":{"get":{"description":"List a VM's domains and DNS verification requirements.","operationId":"list_domains","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"items":{"items":{"properties":{"cname_target":{"type":"string"},"dns_requirements":{},"domain_id":{"format":"uuid","type":"string"},"hostname":{"type":["string","null"]},"state":{"type":"string"},"txt_name":{"type":"string"},"txt_value":{"type":"string"}},"required":["domain_id","state","txt_name","txt_value","cname_target"],"type":"object"},"type":"array"}},"required":["items"],"type":"object"}}},"description":"Success"},"400":{"description":"Invalid arguments"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope or resource permission"},"404":{"description":"Resource not found"},"409":{"description":"Plan allowance or resource capacity exceeded"}},"security":[{"bearerAuth":[]}],"x-required-scope":"read"},"post":{"description":"Register a customer hostname and return its DNS verification requirements.","operationId":"add_domain","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"hostname":{"type":"string"}},"required":["hostname"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"cname_target":{"type":"string"},"dns_requirements":{},"domain_id":{"format":"uuid","type":"string"},"hostname":{"type":["string","null"]},"state":{"type":"string"},"txt_name":{"type":"string"},"txt_value":{"type":"string"}},"required":["domain_id","state","txt_name","txt_value","cname_target"],"type":"object"}}},"description":"Success"},"400":{"description":"Invalid arguments"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope or resource permission"},"404":{"description":"Resource not found"},"409":{"description":"Plan allowance or resource capacity exceeded"}},"security":[{"bearerAuth":[]}],"x-required-scope":"manage"}},"/api/vms/{id}/domains/{domain}":{"delete":{"description":"Retire a VM's customer domain.","operationId":"remove_domain","parameters":[{"in":"path","name":"domain","required":true,"schema":{"format":"uuid","type":"string"}},{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"ok":{"type":"boolean"}},"required":["ok"],"type":"object"}}},"description":"Success"},"400":{"description":"Invalid arguments"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope or resource permission"},"404":{"description":"Resource not found"},"409":{"description":"Plan allowance or resource capacity exceeded"}},"security":[{"bearerAuth":[]}],"x-required-scope":"manage"}},"/api/vms/{id}/email":{"get":{"description":"Get a VM mailbox, including its stable sending and receiving address.","operationId":"get_vm_mailbox","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"account_id":{"format":"uuid","type":"string"},"address":{"type":"string"},"created_at":{"format":"int64","type":"integer"},"enabled":{"type":"boolean"},"id":{"format":"uuid","type":"string"},"vm_id":{"format":"uuid","type":["string","null"]}},"required":["id","account_id","address","enabled","created_at"],"type":"object"}}},"description":"Success"},"400":{"description":"Invalid arguments"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope or resource permission"},"404":{"description":"Resource not found"},"409":{"description":"Plan allowance or resource capacity exceeded"}},"security":[{"bearerAuth":[]}],"x-required-scope":"email_read"}},"/api/vms/{id}/exec":{"post":{"description":"Run a command inside a VM, returning an execution ID to poll. Timeout defaults to 60 seconds, maximum 900.","operationId":"exec_vm","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}},{"in":"header","name":"Idempotency-Key","required":false,"schema":{"maxLength":128,"minLength":1,"type":["string","null"]}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"command":{"maxLength":4096,"minLength":1,"type":"string"},"cwd":{"maxLength":4096,"minLength":1,"type":["string","null"]},"env":{"additionalProperties":{"maxLength":4096,"type":"string"},"maxProperties":64,"propertyNames":{"maxLength":128,"minLength":1},"type":["object","null"]},"timeout_seconds":{"default":60,"format":"int32","maximum":900,"minimum":1,"type":["integer","null"]}},"required":["command"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"execution_id":{"format":"uuid","type":"string"},"state":{"type":"string"}},"required":["execution_id","state"],"type":"object"}}},"description":"Success"},"400":{"description":"Invalid arguments"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope or resource permission"},"404":{"description":"Resource not found"},"409":{"description":"Plan allowance or resource capacity exceeded"}},"security":[{"bearerAuth":[]}],"x-required-scope":"vm_access"}},"/api/vms/{id}/exec/{execution}":{"delete":{"description":"Cancel a guest command and terminate its process group.","operationId":"cancel_execution","parameters":[{"in":"path","name":"execution","required":true,"schema":{"format":"uuid","type":"string"}},{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"ok":{"type":"boolean"}},"required":["ok"],"type":"object"}}},"description":"Success"},"400":{"description":"Invalid arguments"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope or resource permission"},"404":{"description":"Resource not found"},"409":{"description":"Plan allowance or resource capacity exceeded"}},"security":[{"bearerAuth":[]}],"x-required-scope":"vm_access"},"get":{"description":"Poll a guest command's status, separate stdout/stderr, exit code and output truncation flags.","operationId":"get_execution","parameters":[{"in":"path","name":"execution","required":true,"schema":{"format":"uuid","type":"string"}},{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"error":{"type":["string","null"]},"execution_id":{"format":"uuid","type":"string"},"exit_code":{"format":"int32","type":["integer","null"]},"signal":{"format":"int32","type":["integer","null"]},"state":{"type":"string"},"stderr":{"type":"string"},"stderr_truncated":{"type":"boolean"},"stdout":{"type":"string"},"stdout_truncated":{"type":"boolean"}},"required":["execution_id","state","stdout","stderr","stdout_truncated","stderr_truncated"],"type":"object"}}},"description":"Success"},"400":{"description":"Invalid arguments"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope or resource permission"},"404":{"description":"Resource not found"},"409":{"description":"Plan allowance or resource capacity exceeded"}},"security":[{"bearerAuth":[]}],"x-required-scope":"vm_access"}},"/api/vms/{id}/files":{"get":{"description":"Read a bounded range from a guest file; data is base64 unless encoding is utf8.","operationId":"read_file","parameters":[{"in":"query","name":"encoding","required":false,"schema":{"enum":["base64","utf8",null],"type":["string","null"]}},{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}},{"in":"query","name":"length","required":false,"schema":{"default":65536,"format":"int32","maximum":262144,"minimum":1,"type":["integer","null"]}},{"in":"query","name":"offset","required":false,"schema":{"format":"int64","minimum":0,"type":["integer","null"]}},{"in":"query","name":"path","required":true,"schema":{"maxLength":4096,"minLength":1,"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"type":"string"},"eof":{"type":"boolean"},"offset":{"format":"int64","minimum":0,"type":"integer"}},"required":["offset","data","eof"],"type":"object"}}},"description":"Success"},"400":{"description":"Invalid arguments"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope or resource permission"},"404":{"description":"Resource not found"},"409":{"description":"Plan allowance or resource capacity exceeded"}},"security":[{"bearerAuth":[]}],"x-required-scope":"vm_access"}},"/api/vms/{id}/grants/{user}":{"delete":{"description":"Revoke a member's explicit access to a VM.","operationId":"remove_grant","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}},{"in":"path","name":"user","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"ok":{"type":"boolean"}},"required":["ok"],"type":"object"}}},"description":"Success"},"400":{"description":"Invalid arguments"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope or resource permission"},"404":{"description":"Resource not found"},"409":{"description":"Plan allowance or resource capacity exceeded"}},"security":[{"bearerAuth":[]}],"x-required-scope":"manage"},"post":{"description":"Grant VM access to an existing account member.","operationId":"add_grant","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}},{"in":"path","name":"user","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"ok":{"type":"boolean"}},"required":["ok"],"type":"object"}}},"description":"Success"},"400":{"description":"Invalid arguments"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope or resource permission"},"404":{"description":"Resource not found"},"409":{"description":"Plan allowance or resource capacity exceeded"}},"security":[{"bearerAuth":[]}],"x-required-scope":"manage"}},"/api/vms/{id}/resize":{"post":{"description":"Change a stopped VM's reserved memory and disk. Memory may increase or decrease. Disk may only increase. The guest receives the new size the next time it starts. Pool CPU time stays shared.","operationId":"resize_vm","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}},{"in":"header","name":"Idempotency-Key","required":false,"schema":{"maxLength":128,"minLength":1,"type":["string","null"]}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"memory_mib":{"format":"int64","maximum":1048576,"minimum":128,"type":"integer"},"storage_gib":{"format":"int64","maximum":1048576,"minimum":4,"type":"integer"}},"required":["memory_mib","storage_gib"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"applies_on_start":{"type":"boolean"},"operation_id":{"format":"uuid","type":["string","null"]},"vm":{"properties":{"account_id":{"format":"uuid","type":"string"},"desired":{"type":"boolean"},"host_id":{"format":"uuid","type":"string"},"id":{"format":"uuid","type":"string"},"memory_mib":{"format":"int64","minimum":0,"type":"integer"},"name":{"type":"string"},"pool_id":{"format":"uuid","type":["string","null"]},"slot_id":{"format":"uuid","type":"string"},"state":{"type":"string"},"storage_gib":{"format":"int64","minimum":0,"type":"integer"}},"required":["id","account_id","name","slot_id","host_id","memory_mib","storage_gib","desired","state"],"type":"object"}},"required":["vm","applies_on_start"],"type":"object"}}},"description":"Success"},"400":{"description":"Invalid arguments"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope or resource permission"},"404":{"description":"Resource not found"},"409":{"description":"Plan allowance or resource capacity exceeded"}},"security":[{"bearerAuth":[]}],"x-required-scope":"manage"}},"/api/vms/{id}/start":{"post":{"description":"Start a VM; poll the returned operation ID.","operationId":"start_vm","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"operation_id":{"format":"uuid","type":"string"}},"required":["operation_id"],"type":"object"}}},"description":"Success"},"400":{"description":"Invalid arguments"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope or resource permission"},"404":{"description":"Resource not found"},"409":{"description":"Plan allowance or resource capacity exceeded"}},"security":[{"bearerAuth":[]}],"x-required-scope":"manage"}},"/api/vms/{id}/stop":{"post":{"description":"Stop a VM and immediately revoke its active allocations.","operationId":"stop_vm","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"operation_id":{"format":"uuid","type":"string"}},"required":["operation_id"],"type":"object"}}},"description":"Success"},"400":{"description":"Invalid arguments"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope or resource permission"},"404":{"description":"Resource not found"},"409":{"description":"Plan allowance or resource capacity exceeded"}},"security":[{"bearerAuth":[]}],"x-required-scope":"manage"}},"/api/vms/{id}/tcp":{"post":{"description":"Reserve an available public TCP port mapped to a guest port.","operationId":"add_tcp","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"guest_port":{"format":"int32","maximum":65535,"minimum":1,"type":"integer"}},"required":["guest_port"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"guest_port":{"format":"int32","minimum":0,"type":"integer"},"public_port":{"format":"int32","minimum":0,"type":"integer"}},"required":["public_port","guest_port"],"type":"object"}}},"description":"Success"},"400":{"description":"Invalid arguments"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope or resource permission"},"404":{"description":"Resource not found"},"409":{"description":"Plan allowance or resource capacity exceeded"}},"security":[{"bearerAuth":[]}],"x-required-scope":"manage"}},"/api/vms/{id}/tcp/{port}":{"delete":{"description":"Retire a VM's public TCP reservation.","operationId":"remove_tcp","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}},{"in":"path","name":"port","required":true,"schema":{"format":"int32","maximum":65535,"minimum":1,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"ok":{"type":"boolean"}},"required":["ok"],"type":"object"}}},"description":"Success"},"400":{"description":"Invalid arguments"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope or resource permission"},"404":{"description":"Resource not found"},"409":{"description":"Plan allowance or resource capacity exceeded"}},"security":[{"bearerAuth":[]}],"x-required-scope":"manage"}},"/api/vms/{id}/uploads":{"post":{"description":"Begin a verified upload to a guest path; default maximum file size is 64 MiB.","operationId":"begin_upload","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}},{"in":"header","name":"Idempotency-Key","required":false,"schema":{"maxLength":128,"minLength":1,"type":["string","null"]}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"length":{"description":"Expected decoded file bytes. Server policy defaults to 64 MiB; hard limit 1 GiB.","format":"int64","maximum":1073741824,"minimum":0,"type":"integer"},"path":{"maxLength":4096,"minLength":1,"type":"string"},"sha256":{"pattern":"^[0-9a-fA-F]{64}$","type":"string"}},"required":["length","path","sha256"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"complete":{"type":"boolean"},"received":{"format":"int64","minimum":0,"type":"integer"},"upload_id":{"format":"uuid","type":"string"}},"required":["upload_id","received","complete"],"type":"object"}}},"description":"Success"},"400":{"description":"Invalid arguments"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope or resource permission"},"404":{"description":"Resource not found"},"409":{"description":"Plan allowance or resource capacity exceeded"}},"security":[{"bearerAuth":[]}],"x-required-scope":"vm_access"}},"/api/vms/{id}/uploads/{upload}":{"delete":{"description":"Abort an incomplete upload and remove its temporary guest file.","operationId":"abort_upload","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}},{"in":"path","name":"upload","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"ok":{"type":"boolean"}},"required":["ok"],"type":"object"}}},"description":"Success"},"400":{"description":"Invalid arguments"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope or resource permission"},"404":{"description":"Resource not found"},"409":{"description":"Plan allowance or resource capacity exceeded"}},"security":[{"bearerAuth":[]}],"x-required-scope":"vm_access"}},"/api/vms/{id}/uploads/{upload}/chunks":{"put":{"description":"Write a base64 upload chunk of at most 256 KiB decoded; identical retries are safe.","operationId":"write_upload_chunk","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}},{"in":"path","name":"upload","required":true,"schema":{"format":"uuid","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"data":{"contentEncoding":"base64","maxLength":349528,"minLength":1,"type":"string"},"offset":{"format":"int64","minimum":0,"type":"integer"}},"required":["data","offset"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"complete":{"type":"boolean"},"received":{"format":"int64","minimum":0,"type":"integer"},"upload_id":{"format":"uuid","type":"string"}},"required":["upload_id","received","complete"],"type":"object"}}},"description":"Success"},"400":{"description":"Invalid arguments"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope or resource permission"},"404":{"description":"Resource not found"},"409":{"description":"Plan allowance or resource capacity exceeded"}},"security":[{"bearerAuth":[]}],"x-required-scope":"vm_access"}},"/api/vms/{id}/uploads/{upload}/complete":{"post":{"description":"Verify the upload's length and SHA-256, then atomically replace its guest destination.","operationId":"complete_upload","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}},{"in":"path","name":"upload","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"complete":{"type":"boolean"},"received":{"format":"int64","minimum":0,"type":"integer"},"upload_id":{"format":"uuid","type":"string"}},"required":["upload_id","received","complete"],"type":"object"}}},"description":"Success"},"400":{"description":"Invalid arguments"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope or resource permission"},"404":{"description":"Resource not found"},"409":{"description":"Plan allowance or resource capacity exceeded"}},"security":[{"bearerAuth":[]}],"x-required-scope":"vm_access"}}}}