{"openapi":"3.0.3","info":{"title":"Edge Network Agent API","version":"1.1.0","description":"REST API built for AI agents: provision and manage CDN, compute VMs, S3-compatible object storage, DNS, Shield bot protection, and Assist AI site answers on the Edge Network decentralised cloud. Every response includes a tell_user field with a human-readable summary. Every mutating operation supports X-Dry-Run: true (preview without changes) and Idempotency-Key (safe retries). Agents without credentials can sign themselves up autonomously via /agent/signup (Ed25519 keypair + proof-of-work — no card, no human) and immediately deploy free-tier resources. Also available as an MCP server: https://edge.network/mcp (streamable HTTP) or npx @edge-network/mcp (stdio). \n\nVersioning: the current major version is 1, signalled by the X-API-Version response header on every response. Additive changes (new endpoints, new optional fields) ship without a version bump and never break existing integrations. Breaking changes ship under a new URL prefix (e.g. /agent/v2/) with at least 6 months of overlap; during the migration window the old surface returns Deprecation and Sunset headers (RFC 8594). Full policy: https://edge.network/docs/api/versioning. \n\nRate limits: responses carry IETF RateLimit-Limit / RateLimit-Remaining / RateLimit-Reset headers (plus RateLimit-Policy); 429 responses include Retry-After.","contact":{"name":"Edge Network support","email":"support@edge.network","url":"https://edge.network/support"},"termsOfService":"https://edge.network/terms"},"externalDocs":{"description":"Agent API documentation","url":"https://edge.network/docs/agent"},"servers":[{"url":"https://edge.network","description":"Production"}],"security":[{"agentCode":[]}],"tags":[{"name":"Discovery","description":"Self-describing entry points — start at GET /agent."},{"name":"Signup","description":"Autonomous agent self-signup (no card, no human in the loop)."},{"name":"Deploy","description":"High-level orchestration: files or repo in, live URL out."},{"name":"Projects","description":"Group resources, check health, scale, tear down."},{"name":"Compute","description":"Virtual machines, SSH keys, firewall security groups."},{"name":"CDN","description":"Global CDN deployments with free SSL and zero egress."},{"name":"Storage","description":"S3-compatible object storage buckets."},{"name":"DNS","description":"Authoritative DNS zones, records, and AI-powered zone examination."},{"name":"Shield","description":"Free privacy-first CAPTCHA alternative with verified-agent policies."},{"name":"Assist","description":"AI answers widget for any website, grounded in its own content."}],"paths":{"/agent":{"get":{"operationId":"getDiscovery","summary":"Discovery — start here","description":"With an access code: account, budget, enabled products with live limits, projects, and a full self-describing endpoint catalogue. Without credentials: a public onboarding document explaining how to get a code (human-issued or autonomous self-signup).","tags":["Discovery"],"responses":{"200":{"description":"Discovery document (authenticated or public onboarding variant).","headers":{"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TellUserEnvelope"}}}},"400":{"description":"Validation error — the response body explains what to fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Honour Retry-After and the RateLimit-* headers before retrying.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[]}},"/agent/prompt":{"get":{"operationId":"getStarterPrompt","summary":"Starter system prompt","description":"A versioned system prompt that teaches an agent to use Edge safely (dry-run first, budgets, SSH workflow). Public. Pass ?format=text for raw markdown instead of JSON.","tags":["Discovery"],"responses":{"200":{"description":"Success.","headers":{"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TellUserEnvelope"}}}},"400":{"description":"Validation error — the response body explains what to fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Honour Retry-After and the RateLimit-* headers before retrying.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"format","in":"query","required":false,"description":"Set to \"text\" to receive the raw prompt as text/markdown.","schema":{"type":"string","enum":["text"]}}],"security":[]}},"/agent/signup":{"get":{"operationId":"getSignupFlow","summary":"Self-signup flow description","description":"Machine-readable description of the autonomous signup flow: generate an Ed25519 keypair, request a proof-of-work challenge, solve it, and POST the signup. No card, no human. Public.","tags":["Signup"],"responses":{"200":{"description":"Success.","headers":{"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TellUserEnvelope"}}}},"400":{"description":"Validation error — the response body explains what to fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Honour Retry-After and the RateLimit-* headers before retrying.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[]},"post":{"operationId":"createSignup","summary":"Create an account autonomously","description":"Complete self-signup with a solved proof-of-work challenge and an Ed25519 public key. Returns an agent access code for a free explore-tier account that can deploy free-tier resources immediately.","tags":["Signup"],"responses":{"201":{"description":"Account created; the response contains the agent access code (shown once).","headers":{"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TellUserEnvelope"}}}},"400":{"description":"Validation error — the response body explains what to fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Honour Retry-After and the RateLimit-* headers before retrying.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"public_key":{"type":"string","description":"Ed25519 public key (base64)."},"challenge_id":{"type":"string","description":"From POST /agent/signup/challenge."},"nonce":{"type":"string","description":"Proof-of-work solution nonce."},"signature":{"type":"string","description":"Signature over the challenge, proving key possession."}},"required":["public_key","challenge_id","nonce","signature"]}}}},"security":[]}},"/agent/signup/challenge":{"post":{"operationId":"createSignupChallenge","summary":"Request a proof-of-work challenge","description":"First step of self-signup. Returns a challenge to solve (hash-preimage proof-of-work) before POSTing /agent/signup.","tags":["Signup"],"responses":{"201":{"description":"Success.","headers":{"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TellUserEnvelope"}}}},"400":{"description":"Validation error — the response body explains what to fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Honour Retry-After and the RateLimit-* headers before retrying.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[]}},"/agent/signup/bind-email":{"post":{"operationId":"bindSignupEmail","summary":"Nominate a human operator","description":"Guest (self-signed-up) accounts nominate a human operator email. The human receives a claim link; claiming lifts guest-tier restrictions. Requires the guest account's access code.","tags":["Signup"],"responses":{"200":{"description":"Success.","headers":{"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TellUserEnvelope"}}}},"400":{"description":"Validation error — the response body explains what to fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid agent access code. The body includes self-signup pointers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Honour Retry-After and the RateLimit-* headers before retrying.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email","description":"Operator email to send the claim link to."}},"required":["email"]}}}},"security":[{"agentCode":[]}]}},"/agent/signup/status":{"get":{"operationId":"getSignupStatus","summary":"Guest account claim status","description":"Whether this self-signed-up account has been claimed by a human operator yet, and what is unlocked at each stage.","tags":["Signup"],"responses":{"200":{"description":"Success.","headers":{"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TellUserEnvelope"}}}},"400":{"description":"Validation error — the response body explains what to fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid agent access code. The body includes self-signup pointers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Honour Retry-After and the RateLimit-* headers before retrying.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"agentCode":[]}]}},"/agent/deploy/static-site":{"post":{"operationId":"deployStaticSite","summary":"Deploy a static website","description":"One call from files to live URL: creates a storage bucket, uploads files (base64 upload or git clone), configures CDN, domain, SSL, and DNS. Free tier eligible.","tags":["Deploy"],"responses":{"201":{"description":"Deployed. The response includes the live URL.","headers":{"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TellUserEnvelope"}}}},"400":{"description":"Validation error — the response body explains what to fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid agent access code. The body includes self-signup pointers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Honour Retry-After and the RateLimit-* headers before retrying.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"X-Dry-Run","in":"header","required":false,"description":"Set to \"true\" to preview the operation (validation, cost, plan) without making changes.","schema":{"type":"string","enum":["true","false"]}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Unique key for safe retries. Repeating a request with the same key returns the original response instead of re-executing.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project":{"type":"string","description":"Project name (created if it does not exist)."},"source":{"type":"object","description":"Where the files come from.","properties":{"type":{"type":"string","enum":["upload","git"],"description":"\"upload\" for base64 files, \"git\" to clone a repository."},"files":{"type":"array","items":{"$ref":"#/components/schemas/UploadFile"},"description":"Required for type \"upload\"."},"repo":{"type":"string","description":"Required for type \"git\". GitHub/GitLab URL or \"user/repo\" shorthand."},"branch":{"type":"string","default":"main","description":"Git branch or tag."},"path":{"type":"string","description":"Subdirectory to deploy (e.g. \"dist\"). Repository root if omitted."},"token":{"type":"string","description":"Personal access token for private repositories."}},"required":["type"]},"domain":{"type":"string","description":"Custom domain to serve from. SSL auto-provisioned."},"options":{"type":"object","properties":{"spa_mode":{"type":"boolean","description":"Single-page-app fallback routing."},"image_optimization":{"type":"boolean"}}}},"required":["project","source"]}}}},"security":[{"agentCode":[]}]}},"/agent/deploy/app":{"post":{"operationId":"deployApp","summary":"Deploy an application on a VM","description":"Creates a VM, runs a setup script (library script id or inline bash), and optionally fronts it with CDN and DNS. Pass ssh_key or ssh_key_ids to enable SSH access.","tags":["Deploy"],"responses":{"201":{"description":"VM provisioning started. Poll getVm until status is \"running\".","headers":{"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TellUserEnvelope"}}}},"400":{"description":"Validation error — the response body explains what to fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid agent access code. The body includes self-signup pointers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Honour Retry-After and the RateLimit-* headers before retrying.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"X-Dry-Run","in":"header","required":false,"description":"Set to \"true\" to preview the operation (validation, cost, plan) without making changes.","schema":{"type":"string","enum":["true","false"]}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Unique key for safe retries. Repeating a request with the same key returns the original response instead of re-executing.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project":{"type":"string","description":"Project name."},"compute":{"type":"object","properties":{"os":{"type":"string","default":"ubuntu-24.04"},"size":{"type":"string","enum":["nano","small","medium","large","xlarge"],"description":"nano 1vCPU/1GB · small 1/2 · medium 2/4 · large 4/8 · xlarge 8/16."},"region":{"type":"string","default":"london"},"script":{"type":"string","description":"Startup script id from GET /agent/compute/scripts (preferred over setup_script)."},"script_params":{"type":"object","additionalProperties":true,"description":"Parameters for the chosen script."},"setup_script":{"type":"string","description":"Inline bash to run on first boot."},"ssh_key":{"type":"string","description":"SSH public key string; auto-saved and attached."},"ssh_key_ids":{"type":"array","items":{"type":"string"},"description":"Existing SSH key ids to attach."}},"required":["size"]},"security_group_ids":{"type":"array","items":{"type":"string"}},"networking":{"type":"object","properties":{"firewall_rules":{"type":"array","items":{"type":"object","properties":{"port":{"type":"number"},"protocol":{"type":"string","default":"tcp","enum":["tcp","udp"]},"source":{"type":"string","default":"0.0.0.0/0"}},"required":["port"]}}}},"domain":{"type":"string"},"cdn":{"type":"object","properties":{"enabled":{"type":"boolean"}}}},"required":["project","compute"]}}}},"security":[{"agentCode":[]}]}},"/agent/deploy/{projectId}":{"patch":{"operationId":"updateDeployment","summary":"Re-deploy a project","description":"Upload changed files to an existing deployment and optionally purge the CDN cache. Set changed_only to skip files whose MD5 matches.","tags":["Deploy"],"responses":{"200":{"description":"Success.","headers":{"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TellUserEnvelope"}}}},"400":{"description":"Validation error — the response body explains what to fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid agent access code. The body includes self-signup pointers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Honour Retry-After and the RateLimit-* headers before retrying.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"projectId","in":"path","required":true,"description":"Project id returned by the original deploy.","schema":{"type":"string"}},{"name":"X-Dry-Run","in":"header","required":false,"description":"Set to \"true\" to preview the operation (validation, cost, plan) without making changes.","schema":{"type":"string","enum":["true","false"]}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Unique key for safe retries. Repeating a request with the same key returns the original response instead of re-executing.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"source":{"type":"object","properties":{"files":{"type":"array","items":{"$ref":"#/components/schemas/UploadFile"}},"changed_only":{"type":"boolean","description":"Skip unchanged files (MD5 comparison)."}}},"purge_cdn":{"type":"boolean","description":"Purge the CDN cache after upload."}}}}}},"security":[{"agentCode":[]}]}},"/agent/projects":{"get":{"operationId":"listProjects","summary":"List projects","description":"All projects (groupings of resources) on the account.","tags":["Projects"],"responses":{"200":{"description":"Success.","headers":{"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"type":"object","properties":{"projects":{"type":"array","items":{"$ref":"#/components/schemas/Project"}},"tell_user":{"type":"string","description":"Human-readable summary of what happened, for the agent to relay to its operator."}},"required":["projects"]}}}},"400":{"description":"Validation error — the response body explains what to fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid agent access code. The body includes self-signup pointers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Honour Retry-After and the RateLimit-* headers before retrying.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"agentCode":[]}]},"post":{"operationId":"createProject","summary":"Create a project","description":"Create an empty project to group resources under.","tags":["Projects"],"responses":{"201":{"description":"Success.","headers":{"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"type":"object","properties":{"project":{"$ref":"#/components/schemas/Project"},"tell_user":{"type":"string","description":"Human-readable summary of what happened, for the agent to relay to its operator."}},"required":["project"]}}}},"400":{"description":"Validation error — the response body explains what to fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid agent access code. The body includes self-signup pointers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Honour Retry-After and the RateLimit-* headers before retrying.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"X-Dry-Run","in":"header","required":false,"description":"Set to \"true\" to preview the operation (validation, cost, plan) without making changes.","schema":{"type":"string","enum":["true","false"]}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Unique key for safe retries. Repeating a request with the same key returns the original response instead of re-executing.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"}},"required":["name"]}}}},"security":[{"agentCode":[]}]}},"/agent/projects/{id}":{"get":{"operationId":"getProject","summary":"Get a project","description":"One project with its resources.","tags":["Projects"],"responses":{"200":{"description":"Success.","headers":{"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"type":"object","properties":{"project":{"$ref":"#/components/schemas/Project"},"tell_user":{"type":"string","description":"Human-readable summary of what happened, for the agent to relay to its operator."}},"required":["project"]}}}},"400":{"description":"Validation error — the response body explains what to fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid agent access code. The body includes self-signup pointers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Honour Retry-After and the RateLimit-* headers before retrying.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Project id.","schema":{"type":"string"}}],"security":[{"agentCode":[]}]},"delete":{"operationId":"deleteProject","summary":"Teardown a project","description":"Deletes the project and ALL resources in it. Requires the X-Confirm: teardown header as an explicit confirmation.","tags":["Projects"],"responses":{"200":{"description":"Success.","headers":{"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TellUserEnvelope"}}}},"400":{"description":"Validation error — the response body explains what to fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid agent access code. The body includes self-signup pointers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Honour Retry-After and the RateLimit-* headers before retrying.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Project id.","schema":{"type":"string"}},{"name":"X-Confirm","in":"header","required":true,"description":"Must be the literal string \"teardown\".","schema":{"type":"string","enum":["teardown"]}},{"name":"X-Dry-Run","in":"header","required":false,"description":"Set to \"true\" to preview the operation (validation, cost, plan) without making changes.","schema":{"type":"string","enum":["true","false"]}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Unique key for safe retries. Repeating a request with the same key returns the original response instead of re-executing.","schema":{"type":"string"}}],"security":[{"agentCode":[]}]}},"/agent/projects/{id}/health":{"get":{"operationId":"getProjectHealth","summary":"Project health check","description":"Health of every resource in the project: status, key metrics, and suggested fixes.","tags":["Projects"],"responses":{"200":{"description":"Success.","headers":{"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TellUserEnvelope"}}}},"400":{"description":"Validation error — the response body explains what to fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid agent access code. The body includes self-signup pointers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Honour Retry-After and the RateLimit-* headers before retrying.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Project id.","schema":{"type":"string"}}],"security":[{"agentCode":[]}]}},"/agent/projects/{id}/scale":{"post":{"operationId":"scaleProject","summary":"Scale project compute","description":"Resize compute resources in a project (within account limits). Include a reason for the audit log.","tags":["Projects"],"responses":{"200":{"description":"Success.","headers":{"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TellUserEnvelope"}}}},"400":{"description":"Validation error — the response body explains what to fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid agent access code. The body includes self-signup pointers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Honour Retry-After and the RateLimit-* headers before retrying.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Project id.","schema":{"type":"string"}},{"name":"X-Dry-Run","in":"header","required":false,"description":"Set to \"true\" to preview the operation (validation, cost, plan) without making changes.","schema":{"type":"string","enum":["true","false"]}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Unique key for safe retries. Repeating a request with the same key returns the original response instead of re-executing.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"compute":{"type":"object","properties":{"size":{"type":"string","enum":["nano","small","medium","large","xlarge"]}}},"reason":{"type":"string","description":"Why this scaling action is being taken."}}}}}},"security":[{"agentCode":[]}]}},"/agent/compute/vms":{"get":{"operationId":"listVms","summary":"List VMs","description":"All virtual machines on the account.","tags":["Compute"],"responses":{"200":{"description":"Success.","headers":{"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"type":"object","properties":{"vms":{"type":"array","items":{"$ref":"#/components/schemas/Vm"}},"tell_user":{"type":"string","description":"Human-readable summary of what happened, for the agent to relay to its operator."}},"required":["vms"]}}}},"400":{"description":"Validation error — the response body explains what to fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid agent access code. The body includes self-signup pointers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Honour Retry-After and the RateLimit-* headers before retrying.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"agentCode":[]}]},"post":{"operationId":"createVm","summary":"Create a VM","description":"Create a VM directly. Pass ssh_key or ssh_key_ids for SSH access — or attach a key later with attachVmSshKey (never recreate a VM just to add a key). Use size, or override vcpu/ram/disk individually.","tags":["Compute"],"responses":{"201":{"description":"VM created. Poll getVm until status is \"running\" before SSHing.","headers":{"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"type":"object","properties":{"vm":{"$ref":"#/components/schemas/Vm"},"tell_user":{"type":"string","description":"Human-readable summary of what happened, for the agent to relay to its operator."}},"required":["vm"]}}}},"400":{"description":"Validation error — the response body explains what to fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid agent access code. The body includes self-signup pointers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Honour Retry-After and the RateLimit-* headers before retrying.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"X-Dry-Run","in":"header","required":false,"description":"Set to \"true\" to preview the operation (validation, cost, plan) without making changes.","schema":{"type":"string","enum":["true","false"]}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Unique key for safe retries. Repeating a request with the same key returns the original response instead of re-executing.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"os":{"type":"string","default":"ubuntu-24.04","description":"OS template id from listOsTemplates."},"size":{"type":"string","enum":["nano","small","medium","large","xlarge"]},"vcpu":{"type":"number","description":"Override vCPU count."},"ram":{"type":"number","description":"Override RAM in GB."},"disk":{"type":"number","description":"Override disk in GB."},"region":{"type":"string","default":"london","description":"Region id from listRegions."},"ssh_key":{"type":"string","description":"SSH public key string. Auto-saved and attached."},"ssh_key_ids":{"type":"array","items":{"type":"string"}},"script":{"type":"string","description":"Startup script id from listComputeScripts."},"script_params":{"type":"object","additionalProperties":true},"setup_script":{"type":"string","description":"Inline bash for first boot. Mutually exclusive with script."},"security_group_ids":{"type":"array","items":{"type":"string"}}},"required":["name"]}}}},"security":[{"agentCode":[]}]}},"/agent/compute/vms/{id}":{"get":{"operationId":"getVm","summary":"Get a VM","description":"VM details, live metrics, attached SSH keys, and a ready-to-use ssh command. Poll until status is \"running\".","tags":["Compute"],"responses":{"200":{"description":"Success.","headers":{"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"type":"object","properties":{"vm":{"$ref":"#/components/schemas/Vm"},"tell_user":{"type":"string","description":"Human-readable summary of what happened, for the agent to relay to its operator."}},"required":["vm"]}}}},"400":{"description":"Validation error — the response body explains what to fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid agent access code. The body includes self-signup pointers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Honour Retry-After and the RateLimit-* headers before retrying.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"VM id.","schema":{"type":"string"}}],"security":[{"agentCode":[]}]}},"/agent/compute/os-templates":{"get":{"operationId":"listOsTemplates","summary":"List OS templates","description":"Operating systems available for VM creation.","tags":["Compute"],"responses":{"200":{"description":"Success.","headers":{"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"type":"object","properties":{"os_templates":{"type":"array","items":{"$ref":"#/components/schemas/OsTemplate"}},"tell_user":{"type":"string","description":"Human-readable summary of what happened, for the agent to relay to its operator."}},"required":["os_templates"]}}}},"400":{"description":"Validation error — the response body explains what to fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid agent access code. The body includes self-signup pointers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Honour Retry-After and the RateLimit-* headers before retrying.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"agentCode":[]}]}},"/agent/compute/regions":{"get":{"operationId":"listRegions","summary":"List compute regions","description":"Regions available to this account for VM deployment.","tags":["Compute"],"responses":{"200":{"description":"Success.","headers":{"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"type":"object","properties":{"regions":{"type":"array","items":{"$ref":"#/components/schemas/Region"}},"tell_user":{"type":"string","description":"Human-readable summary of what happened, for the agent to relay to its operator."}},"required":["regions"]}}}},"400":{"description":"Validation error — the response body explains what to fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid agent access code. The body includes self-signup pointers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Honour Retry-After and the RateLimit-* headers before retrying.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"agentCode":[]}]}},"/agent/compute/scripts":{"get":{"operationId":"listComputeScripts","summary":"List startup scripts","description":"Edge library scripts (docker, nodejs, wordpress, …) and custom scripts, with their parameters. Pass an id as \"script\" when creating a VM.","tags":["Compute"],"responses":{"200":{"description":"Success.","headers":{"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"type":"object","properties":{"scripts":{"type":"array","items":{"$ref":"#/components/schemas/ComputeScript"}},"tell_user":{"type":"string","description":"Human-readable summary of what happened, for the agent to relay to its operator."}},"required":["scripts"]}}}},"400":{"description":"Validation error — the response body explains what to fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid agent access code. The body includes self-signup pointers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Honour Retry-After and the RateLimit-* headers before retrying.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"agentCode":[]}]}},"/agent/compute/ssh-keys":{"get":{"operationId":"listSshKeys","summary":"List SSH keys","description":"SSH keys saved on the account.","tags":["Compute"],"responses":{"200":{"description":"Success.","headers":{"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"type":"object","properties":{"ssh_keys":{"type":"array","items":{"$ref":"#/components/schemas/SshKey"}},"tell_user":{"type":"string","description":"Human-readable summary of what happened, for the agent to relay to its operator."}},"required":["ssh_keys"]}}}},"400":{"description":"Validation error — the response body explains what to fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid agent access code. The body includes self-signup pointers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Honour Retry-After and the RateLimit-* headers before retrying.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"agentCode":[]}]},"post":{"operationId":"createSshKey","summary":"Save an SSH key","description":"Save a public key on the account. Returns an id usable in ssh_key_ids at VM creation, or attach later with attachVmSshKey.","tags":["Compute"],"responses":{"201":{"description":"Success.","headers":{"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"type":"object","properties":{"ssh_key":{"$ref":"#/components/schemas/SshKey"},"tell_user":{"type":"string","description":"Human-readable summary of what happened, for the agent to relay to its operator."}},"required":["ssh_key"]}}}},"400":{"description":"Validation error — the response body explains what to fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid agent access code. The body includes self-signup pointers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Honour Retry-After and the RateLimit-* headers before retrying.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"X-Dry-Run","in":"header","required":false,"description":"Set to \"true\" to preview the operation (validation, cost, plan) without making changes.","schema":{"type":"string","enum":["true","false"]}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Unique key for safe retries. Repeating a request with the same key returns the original response instead of re-executing.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Friendly name, e.g. \"alice-laptop\"."},"public_key":{"type":"string","description":"ssh-ed25519, ssh-rsa, or ecdsa-sha2-* public key string."}},"required":["name","public_key"]}}}},"security":[{"agentCode":[]}]}},"/agent/compute/ssh-keys/{id}":{"delete":{"operationId":"deleteSshKey","summary":"Delete an SSH key","description":"Delete a saved key. It must not be attached to any VM (detach first with detachVmSshKey).","tags":["Compute"],"responses":{"200":{"description":"Success.","headers":{"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TellUserEnvelope"}}}},"400":{"description":"Validation error — the response body explains what to fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid agent access code. The body includes self-signup pointers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Honour Retry-After and the RateLimit-* headers before retrying.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"SSH key id.","schema":{"type":"string"}},{"name":"X-Dry-Run","in":"header","required":false,"description":"Set to \"true\" to preview the operation (validation, cost, plan) without making changes.","schema":{"type":"string","enum":["true","false"]}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Unique key for safe retries. Repeating a request with the same key returns the original response instead of re-executing.","schema":{"type":"string"}}],"security":[{"agentCode":[]}]}},"/agent/compute/vms/{id}/ssh-keys":{"get":{"operationId":"listVmSshKeys","summary":"List keys attached to a VM","description":"SSH keys currently attached to this VM.","tags":["Compute"],"responses":{"200":{"description":"Success.","headers":{"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"type":"object","properties":{"ssh_keys":{"type":"array","items":{"$ref":"#/components/schemas/SshKey"}},"tell_user":{"type":"string","description":"Human-readable summary of what happened, for the agent to relay to its operator."}},"required":["ssh_keys"]}}}},"400":{"description":"Validation error — the response body explains what to fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid agent access code. The body includes self-signup pointers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Honour Retry-After and the RateLimit-* headers before retrying.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"VM id.","schema":{"type":"string"}}],"security":[{"agentCode":[]}]}},"/agent/compute/vms/{id}/ssh-keys/{keyId}":{"post":{"operationId":"attachVmSshKey","summary":"Attach an SSH key to a VM","description":"Attach an existing key to a VM after creation — pushed to authorized_keys on running VMs via the guest agent (~10s). Never recreate a VM to add a key.","tags":["Compute"],"responses":{"200":{"description":"Success.","headers":{"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TellUserEnvelope"}}}},"400":{"description":"Validation error — the response body explains what to fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid agent access code. The body includes self-signup pointers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Honour Retry-After and the RateLimit-* headers before retrying.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"VM id.","schema":{"type":"string"}},{"name":"keyId","in":"path","required":true,"description":"SSH key id.","schema":{"type":"string"}},{"name":"X-Dry-Run","in":"header","required":false,"description":"Set to \"true\" to preview the operation (validation, cost, plan) without making changes.","schema":{"type":"string","enum":["true","false"]}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Unique key for safe retries. Repeating a request with the same key returns the original response instead of re-executing.","schema":{"type":"string"}}],"security":[{"agentCode":[]}]},"delete":{"operationId":"detachVmSshKey","summary":"Detach an SSH key from a VM","description":"Remove a key from the VM (deleted from authorized_keys on running VMs).","tags":["Compute"],"responses":{"200":{"description":"Success.","headers":{"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TellUserEnvelope"}}}},"400":{"description":"Validation error — the response body explains what to fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid agent access code. The body includes self-signup pointers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Honour Retry-After and the RateLimit-* headers before retrying.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"VM id.","schema":{"type":"string"}},{"name":"keyId","in":"path","required":true,"description":"SSH key id.","schema":{"type":"string"}},{"name":"X-Dry-Run","in":"header","required":false,"description":"Set to \"true\" to preview the operation (validation, cost, plan) without making changes.","schema":{"type":"string","enum":["true","false"]}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Unique key for safe retries. Repeating a request with the same key returns the original response instead of re-executing.","schema":{"type":"string"}}],"security":[{"agentCode":[]}]}},"/agent/compute/firewall":{"get":{"operationId":"listSecurityGroups","summary":"List security groups","description":"All security groups and their firewall rules.","tags":["Compute"],"responses":{"200":{"description":"Success.","headers":{"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"type":"object","properties":{"security_groups":{"type":"array","items":{"$ref":"#/components/schemas/SecurityGroup"}},"tell_user":{"type":"string","description":"Human-readable summary of what happened, for the agent to relay to its operator."}},"required":["security_groups"]}}}},"400":{"description":"Validation error — the response body explains what to fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid agent access code. The body includes self-signup pointers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Honour Retry-After and the RateLimit-* headers before retrying.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"agentCode":[]}]},"post":{"operationId":"createSecurityGroup","summary":"Create a security group","description":"Create a security group with inbound/outbound firewall rules, then attach it to VMs.","tags":["Compute"],"responses":{"201":{"description":"Success.","headers":{"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"type":"object","properties":{"security_group":{"$ref":"#/components/schemas/SecurityGroup"},"tell_user":{"type":"string","description":"Human-readable summary of what happened, for the agent to relay to its operator."}},"required":["security_group"]}}}},"400":{"description":"Validation error — the response body explains what to fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid agent access code. The body includes self-signup pointers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Honour Retry-After and the RateLimit-* headers before retrying.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"X-Dry-Run","in":"header","required":false,"description":"Set to \"true\" to preview the operation (validation, cost, plan) without making changes.","schema":{"type":"string","enum":["true","false"]}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Unique key for safe retries. Repeating a request with the same key returns the original response instead of re-executing.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"rules":{"type":"array","items":{"type":"object","properties":{"direction":{"type":"string","enum":["inbound","outbound"],"default":"inbound"},"protocol":{"type":"string","enum":["tcp","udp","icmp","all"],"default":"tcp"},"portRange":{"type":"string","description":"Port or range, e.g. \"80\" or \"8000-9000\". Omit for all ports."},"source":{"type":"string","default":"0.0.0.0/0"}}}}},"required":["name"]}}}},"security":[{"agentCode":[]}]}},"/agent/compute/firewall/{groupId}":{"get":{"operationId":"getSecurityGroup","summary":"Get a security group","description":"One security group with its rules.","tags":["Compute"],"responses":{"200":{"description":"Success.","headers":{"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"type":"object","properties":{"security_group":{"$ref":"#/components/schemas/SecurityGroup"},"tell_user":{"type":"string","description":"Human-readable summary of what happened, for the agent to relay to its operator."}},"required":["security_group"]}}}},"400":{"description":"Validation error — the response body explains what to fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid agent access code. The body includes self-signup pointers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Honour Retry-After and the RateLimit-* headers before retrying.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"groupId","in":"path","required":true,"description":"Security group id.","schema":{"type":"string"}}],"security":[{"agentCode":[]}]}},"/agent/compute/vms/{id}/firewall/{groupId}":{"post":{"operationId":"attachSecurityGroup","summary":"Attach a security group to a VM","description":"Apply a security group's firewall rules to a VM. Ensure tcp/22 is allowed if you need SSH (the built-in \"allow-ssh\" group covers it).","tags":["Compute"],"responses":{"200":{"description":"Success.","headers":{"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TellUserEnvelope"}}}},"400":{"description":"Validation error — the response body explains what to fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid agent access code. The body includes self-signup pointers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Honour Retry-After and the RateLimit-* headers before retrying.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"VM id.","schema":{"type":"string"}},{"name":"groupId","in":"path","required":true,"description":"Security group id.","schema":{"type":"string"}},{"name":"X-Dry-Run","in":"header","required":false,"description":"Set to \"true\" to preview the operation (validation, cost, plan) without making changes.","schema":{"type":"string","enum":["true","false"]}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Unique key for safe retries. Repeating a request with the same key returns the original response instead of re-executing.","schema":{"type":"string"}}],"security":[{"agentCode":[]}]},"delete":{"operationId":"detachSecurityGroup","summary":"Detach a security group from a VM","description":"Remove a security group's rules from a VM.","tags":["Compute"],"responses":{"200":{"description":"Success.","headers":{"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TellUserEnvelope"}}}},"400":{"description":"Validation error — the response body explains what to fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid agent access code. The body includes self-signup pointers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Honour Retry-After and the RateLimit-* headers before retrying.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"VM id.","schema":{"type":"string"}},{"name":"groupId","in":"path","required":true,"description":"Security group id.","schema":{"type":"string"}},{"name":"X-Dry-Run","in":"header","required":false,"description":"Set to \"true\" to preview the operation (validation, cost, plan) without making changes.","schema":{"type":"string","enum":["true","false"]}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Unique key for safe retries. Repeating a request with the same key returns the original response instead of re-executing.","schema":{"type":"string"}}],"security":[{"agentCode":[]}]}},"/agent/cdn/deployments":{"get":{"operationId":"listCdnDeployments","summary":"List CDN deployments","description":"All CDN deployments on the account, with domains and origin configuration.","tags":["CDN"],"responses":{"200":{"description":"Success.","headers":{"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"type":"object","properties":{"deployments":{"type":"array","items":{"$ref":"#/components/schemas/CdnDeployment"}},"tell_user":{"type":"string","description":"Human-readable summary of what happened, for the agent to relay to its operator."}},"required":["deployments"]}}}},"400":{"description":"Validation error — the response body explains what to fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid agent access code. The body includes self-signup pointers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Honour Retry-After and the RateLimit-* headers before retrying.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"agentCode":[]}]}},"/agent/storage/buckets":{"get":{"operationId":"listBuckets","summary":"List storage buckets","description":"All S3-compatible object storage buckets on the account.","tags":["Storage"],"responses":{"200":{"description":"Success.","headers":{"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"type":"object","properties":{"buckets":{"type":"array","items":{"$ref":"#/components/schemas/StorageBucket"}},"tell_user":{"type":"string","description":"Human-readable summary of what happened, for the agent to relay to its operator."}},"required":["buckets"]}}}},"400":{"description":"Validation error — the response body explains what to fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid agent access code. The body includes self-signup pointers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Honour Retry-After and the RateLimit-* headers before retrying.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"agentCode":[]}]},"post":{"operationId":"createBucket","summary":"Create a bucket","description":"Create an S3-compatible storage bucket. Names are 3–63 chars, lowercase, hyphens allowed.","tags":["Storage"],"responses":{"201":{"description":"Success.","headers":{"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"type":"object","properties":{"bucket":{"$ref":"#/components/schemas/StorageBucket"},"tell_user":{"type":"string","description":"Human-readable summary of what happened, for the agent to relay to its operator."}},"required":["bucket"]}}}},"400":{"description":"Validation error — the response body explains what to fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid agent access code. The body includes self-signup pointers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Honour Retry-After and the RateLimit-* headers before retrying.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"X-Dry-Run","in":"header","required":false,"description":"Set to \"true\" to preview the operation (validation, cost, plan) without making changes.","schema":{"type":"string","enum":["true","false"]}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Unique key for safe retries. Repeating a request with the same key returns the original response instead of re-executing.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":3,"maxLength":63,"pattern":"^[a-z0-9][a-z0-9-]*[a-z0-9]$"}},"required":["name"]}}}},"security":[{"agentCode":[]}]}},"/agent/storage/buckets/{name}/upload":{"post":{"operationId":"uploadToBucket","summary":"Upload files to a bucket","description":"Upload base64-encoded files to an existing bucket. Set changed_only to skip files whose MD5 matches an existing object.","tags":["Storage"],"responses":{"200":{"description":"Success.","headers":{"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TellUserEnvelope"}}}},"400":{"description":"Validation error — the response body explains what to fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid agent access code. The body includes self-signup pointers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Honour Retry-After and the RateLimit-* headers before retrying.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"name","in":"path","required":true,"description":"Bucket name.","schema":{"type":"string"}},{"name":"X-Dry-Run","in":"header","required":false,"description":"Set to \"true\" to preview the operation (validation, cost, plan) without making changes.","schema":{"type":"string","enum":["true","false"]}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Unique key for safe retries. Repeating a request with the same key returns the original response instead of re-executing.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"files":{"type":"array","items":{"$ref":"#/components/schemas/UploadFile"}},"changed_only":{"type":"boolean"}},"required":["files"]}}}},"security":[{"agentCode":[]}]}},"/agent/dns/zones":{"get":{"operationId":"listDnsZones","summary":"List DNS zones","description":"All DNS zones on the account.","tags":["DNS"],"responses":{"200":{"description":"Success.","headers":{"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"type":"object","properties":{"zones":{"type":"array","items":{"$ref":"#/components/schemas/DnsZone"}},"tell_user":{"type":"string","description":"Human-readable summary of what happened, for the agent to relay to its operator."}},"required":["zones"]}}}},"400":{"description":"Validation error — the response body explains what to fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid agent access code. The body includes self-signup pointers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Honour Retry-After and the RateLimit-* headers before retrying.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"agentCode":[]}]},"post":{"operationId":"createDnsZone","summary":"Create a DNS zone","description":"Create an authoritative DNS zone for a domain. Point the domain's nameservers at Edge to activate it.","tags":["DNS"],"responses":{"201":{"description":"Success.","headers":{"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"type":"object","properties":{"zone":{"$ref":"#/components/schemas/DnsZone"},"tell_user":{"type":"string","description":"Human-readable summary of what happened, for the agent to relay to its operator."}},"required":["zone"]}}}},"400":{"description":"Validation error — the response body explains what to fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid agent access code. The body includes self-signup pointers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Honour Retry-After and the RateLimit-* headers before retrying.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"X-Dry-Run","in":"header","required":false,"description":"Set to \"true\" to preview the operation (validation, cost, plan) without making changes.","schema":{"type":"string","enum":["true","false"]}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Unique key for safe retries. Repeating a request with the same key returns the original response instead of re-executing.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string","description":"Domain name, e.g. \"example.com\"."}},"required":["domain"]}}}},"security":[{"agentCode":[]}]}},"/agent/dns/zones/{id}":{"get":{"operationId":"getDnsZone","summary":"Get a DNS zone","description":"Zone details including all records.","tags":["DNS"],"responses":{"200":{"description":"Success.","headers":{"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"type":"object","properties":{"zone":{"$ref":"#/components/schemas/DnsZone"},"tell_user":{"type":"string","description":"Human-readable summary of what happened, for the agent to relay to its operator."}},"required":["zone"]}}}},"400":{"description":"Validation error — the response body explains what to fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid agent access code. The body includes self-signup pointers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Honour Retry-After and the RateLimit-* headers before retrying.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Zone id.","schema":{"type":"string"}}],"security":[{"agentCode":[]}]}},"/agent/dns/zones/{id}/records":{"post":{"operationId":"createDnsRecord","summary":"Add a DNS record","description":"Add a record to a zone. MX records require priority.","tags":["DNS"],"responses":{"201":{"description":"Success.","headers":{"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"type":"object","properties":{"record":{"$ref":"#/components/schemas/DnsRecord"},"tell_user":{"type":"string","description":"Human-readable summary of what happened, for the agent to relay to its operator."}},"required":["record"]}}}},"400":{"description":"Validation error — the response body explains what to fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid agent access code. The body includes self-signup pointers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Honour Retry-After and the RateLimit-* headers before retrying.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Zone id.","schema":{"type":"string"}},{"name":"X-Dry-Run","in":"header","required":false,"description":"Set to \"true\" to preview the operation (validation, cost, plan) without making changes.","schema":{"type":"string","enum":["true","false"]}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Unique key for safe retries. Repeating a request with the same key returns the original response instead of re-executing.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["A","AAAA","CNAME","MX","TXT","NS"]},"name":{"type":"string","description":"\"www\", \"@\" for root, etc."},"data":{"type":"string","description":"IP address, hostname, or text value."},"ttl":{"type":"number","default":300},"priority":{"type":"number","description":"Required for MX records."}},"required":["type","name","data"]}}}},"security":[{"agentCode":[]}]}},"/agent/dns/zones/{id}/examine":{"get":{"operationId":"getDnsExamination","summary":"Latest DNS examination result","description":"The most recent AI-powered DNS examination for this zone.","tags":["DNS"],"responses":{"200":{"description":"Success.","headers":{"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TellUserEnvelope"}}}},"400":{"description":"Validation error — the response body explains what to fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid agent access code. The body includes self-signup pointers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Honour Retry-After and the RateLimit-* headers before retrying.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Zone id.","schema":{"type":"string"}}],"security":[{"agentCode":[]}]},"post":{"operationId":"runDnsExamination","summary":"Run a DNS examination","description":"AI-powered zone audit: email deliverability (SPF/DKIM/DMARC), security (CAA), nameservers, web records, and best practices. Returns a health score and actionable fixes. Takes up to 30 seconds.","tags":["DNS"],"responses":{"200":{"description":"Success.","headers":{"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TellUserEnvelope"}}}},"400":{"description":"Validation error — the response body explains what to fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid agent access code. The body includes self-signup pointers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Honour Retry-After and the RateLimit-* headers before retrying.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Zone id.","schema":{"type":"string"}}],"security":[{"agentCode":[]}]}},"/agent/dns/test-domains":{"get":{"operationId":"listTestDomains","summary":"List test.network domains","description":"Your registered test.network subdomains.","tags":["DNS"],"responses":{"200":{"description":"Success.","headers":{"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"type":"object","properties":{"domains":{"type":"array","items":{"$ref":"#/components/schemas/TestDomain"}},"tell_user":{"type":"string","description":"Human-readable summary of what happened, for the agent to relay to its operator."}},"required":["domains"]}}}},"400":{"description":"Validation error — the response body explains what to fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid agent access code. The body includes self-signup pointers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Honour Retry-After and the RateLimit-* headers before retrying.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"agentCode":[]}]},"post":{"operationId":"createTestDomain","summary":"Register a test.network subdomain","description":"Instant subdomain on test.network ($1/month) — useful for previews and demos. Billable: not available to unclaimed guest accounts.","tags":["DNS"],"responses":{"201":{"description":"Success.","headers":{"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TellUserEnvelope"}}}},"400":{"description":"Validation error — the response body explains what to fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid agent access code. The body includes self-signup pointers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Honour Retry-After and the RateLimit-* headers before retrying.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"X-Dry-Run","in":"header","required":false,"description":"Set to \"true\" to preview the operation (validation, cost, plan) without making changes.","schema":{"type":"string","enum":["true","false"]}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Unique key for safe retries. Repeating a request with the same key returns the original response instead of re-executing.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"subdomain":{"type":"string","description":"e.g. \"my-project\" → my-project.test.network."}},"required":["subdomain"]}}}},"security":[{"agentCode":[]}]}},"/agent/dns/test-domains/check/{subdomain}":{"get":{"operationId":"checkTestDomain","summary":"Check test.network availability","description":"Whether a test.network subdomain is available to register.","tags":["DNS"],"responses":{"200":{"description":"Success.","headers":{"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TellUserEnvelope"}}}},"400":{"description":"Validation error — the response body explains what to fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid agent access code. The body includes self-signup pointers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Honour Retry-After and the RateLimit-* headers before retrying.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"subdomain","in":"path","required":true,"description":"Subdomain to check.","schema":{"type":"string"}}],"security":[{"agentCode":[]}]}},"/agent/dns/test-domains/{id}":{"delete":{"operationId":"deleteTestDomain","summary":"Delete a test.network domain","description":"Release a test.network subdomain. Billing stops immediately.","tags":["DNS"],"responses":{"200":{"description":"Success.","headers":{"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TellUserEnvelope"}}}},"400":{"description":"Validation error — the response body explains what to fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid agent access code. The body includes self-signup pointers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Honour Retry-After and the RateLimit-* headers before retrying.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Test domain id.","schema":{"type":"string"}},{"name":"X-Dry-Run","in":"header","required":false,"description":"Set to \"true\" to preview the operation (validation, cost, plan) without making changes.","schema":{"type":"string","enum":["true","false"]}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Unique key for safe retries. Repeating a request with the same key returns the original response instead of re-executing.","schema":{"type":"string"}}],"security":[{"agentCode":[]}]}},"/agent/shield/widgets":{"get":{"operationId":"listShieldWidgets","summary":"List Shield widgets","description":"All Edge Shield bot-protection widgets (sitekeys) on the account.","tags":["Shield"],"responses":{"200":{"description":"Success.","headers":{"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"type":"object","properties":{"widgets":{"type":"array","items":{"$ref":"#/components/schemas/ShieldWidget"}},"tell_user":{"type":"string","description":"Human-readable summary of what happened, for the agent to relay to its operator."}},"required":["widgets"]}}}},"400":{"description":"Validation error — the response body explains what to fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid agent access code. The body includes self-signup pointers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Honour Retry-After and the RateLimit-* headers before retrying.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"agentCode":[]}]},"post":{"operationId":"createShieldWidget","summary":"Create a Shield widget","description":"Create a bot-protection widget for a form or page. Free, unlimited. Returns the sitekey, the secret (shown ONCE — store server-side), and a ready-to-paste embed snippet.","tags":["Shield"],"responses":{"201":{"description":"Success.","headers":{"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"type":"object","properties":{"widget":{"$ref":"#/components/schemas/ShieldWidget"},"tell_user":{"type":"string","description":"Human-readable summary of what happened, for the agent to relay to its operator."}},"required":["widget"]}}}},"400":{"description":"Validation error — the response body explains what to fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid agent access code. The body includes self-signup pointers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Honour Retry-After and the RateLimit-* headers before retrying.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"X-Dry-Run","in":"header","required":false,"description":"Set to \"true\" to preview the operation (validation, cost, plan) without making changes.","schema":{"type":"string","enum":["true","false"]}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Unique key for safe retries. Repeating a request with the same key returns the original response instead of re-executing.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Friendly name, e.g. \"Contact form\"."},"hostnames":{"type":"array","items":{"type":"string"},"description":"Hostnames allowed to use this widget. Empty = any."},"mode":{"type":"string","enum":["managed","non-interactive","invisible"],"default":"managed","description":"managed: invisible for humans, one-click check when suspicious. non-interactive: never asks for input. invisible: verify via JS API only."},"agent_policy":{"type":"string","enum":["allow","challenge","block"],"default":"allow","description":"Treatment of cryptographically verified AI agents (Web Bot Auth)."}},"required":["name"]}}}},"security":[{"agentCode":[]}]}},"/agent/shield/widgets/{id}":{"patch":{"operationId":"updateShieldWidget","summary":"Update a Shield widget","description":"Change name, hostnames, mode, or agent_policy.","tags":["Shield"],"responses":{"200":{"description":"Success.","headers":{"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"type":"object","properties":{"widget":{"$ref":"#/components/schemas/ShieldWidget"},"tell_user":{"type":"string","description":"Human-readable summary of what happened, for the agent to relay to its operator."}},"required":["widget"]}}}},"400":{"description":"Validation error — the response body explains what to fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid agent access code. The body includes self-signup pointers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Honour Retry-After and the RateLimit-* headers before retrying.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Widget id.","schema":{"type":"string"}},{"name":"X-Dry-Run","in":"header","required":false,"description":"Set to \"true\" to preview the operation (validation, cost, plan) without making changes.","schema":{"type":"string","enum":["true","false"]}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Unique key for safe retries. Repeating a request with the same key returns the original response instead of re-executing.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"hostnames":{"type":"array","items":{"type":"string"}},"mode":{"type":"string","enum":["managed","non-interactive","invisible"]},"agent_policy":{"type":"string","enum":["allow","challenge","block"]}}}}}},"security":[{"agentCode":[]}]},"delete":{"operationId":"deleteShieldWidget","summary":"Revoke a Shield widget","description":"The widget's sitekey and secret stop working immediately.","tags":["Shield"],"responses":{"200":{"description":"Success.","headers":{"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TellUserEnvelope"}}}},"400":{"description":"Validation error — the response body explains what to fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid agent access code. The body includes self-signup pointers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Honour Retry-After and the RateLimit-* headers before retrying.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Widget id.","schema":{"type":"string"}},{"name":"X-Dry-Run","in":"header","required":false,"description":"Set to \"true\" to preview the operation (validation, cost, plan) without making changes.","schema":{"type":"string","enum":["true","false"]}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Unique key for safe retries. Repeating a request with the same key returns the original response instead of re-executing.","schema":{"type":"string"}}],"security":[{"agentCode":[]}]}},"/agent/shield/widgets/{id}/stats":{"get":{"operationId":"getShieldWidgetStats","summary":"Shield widget traffic stats","description":"Hourly stats: challenges issued/solved, humanity scores, verifications, blocked replays, verified agents.","tags":["Shield"],"responses":{"200":{"description":"Success.","headers":{"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TellUserEnvelope"}}}},"400":{"description":"Validation error — the response body explains what to fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid agent access code. The body includes self-signup pointers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Honour Retry-After and the RateLimit-* headers before retrying.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Widget id.","schema":{"type":"string"}},{"name":"hours","in":"query","required":false,"description":"Window size in hours (default 24, max 720).","schema":{"type":"integer","minimum":1,"maximum":720,"default":24}}],"security":[{"agentCode":[]}]}},"/agent/assist/sites":{"get":{"operationId":"listAssistSites","summary":"List Assist sites","description":"All Edge Assist sites with month usage, caps, and index status.","tags":["Assist"],"responses":{"200":{"description":"Success.","headers":{"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"type":"object","properties":{"sites":{"type":"array","items":{"$ref":"#/components/schemas/AssistSite"}},"tell_user":{"type":"string","description":"Human-readable summary of what happened, for the agent to relay to its operator."}},"required":["sites"]}}}},"400":{"description":"Validation error — the response body explains what to fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid agent access code. The body includes self-signup pointers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Honour Retry-After and the RateLimit-* headers before retrying.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"agentCode":[]}]},"post":{"operationId":"createAssistSite","summary":"Create an Assist site","description":"AI answers for a website, grounded in its own content. Returns the sitekey and a one-line embed snippet. Free tier: 250 answered questions/month. After creating, host a content index and trigger reingestAssistSite.","tags":["Assist"],"responses":{"201":{"description":"Success.","headers":{"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"type":"object","properties":{"site":{"$ref":"#/components/schemas/AssistSite"},"tell_user":{"type":"string","description":"Human-readable summary of what happened, for the agent to relay to its operator."}},"required":["site"]}}}},"400":{"description":"Validation error — the response body explains what to fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid agent access code. The body includes self-signup pointers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Honour Retry-After and the RateLimit-* headers before retrying.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"X-Dry-Run","in":"header","required":false,"description":"Set to \"true\" to preview the operation (validation, cost, plan) without making changes.","schema":{"type":"string","enum":["true","false"]}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Unique key for safe retries. Repeating a request with the same key returns the original response instead of re-executing.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Friendly name, e.g. \"Docs site\"."},"hostname":{"type":"string","description":"Hostname the widget runs on. Origin-enforced: the sitekey only works there."},"index_url":{"type":"string","format":"uri","description":"Public URL of the content index JSON: { \"pages\": [{ \"url\", \"title\", \"text\" }] }. Can be set later."},"site_prompt":{"type":"string","description":"Optional instructions steering answers (tone, priorities, things to avoid)."}},"required":["name","hostname"]}}}},"security":[{"agentCode":[]}]}},"/agent/assist/sites/{id}":{"patch":{"operationId":"updateAssistSite","summary":"Update an Assist site","description":"Change name, hostname, index_url, or site_prompt.","tags":["Assist"],"responses":{"200":{"description":"Success.","headers":{"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"type":"object","properties":{"site":{"$ref":"#/components/schemas/AssistSite"},"tell_user":{"type":"string","description":"Human-readable summary of what happened, for the agent to relay to its operator."}},"required":["site"]}}}},"400":{"description":"Validation error — the response body explains what to fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid agent access code. The body includes self-signup pointers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Honour Retry-After and the RateLimit-* headers before retrying.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Assist site id.","schema":{"type":"string"}},{"name":"X-Dry-Run","in":"header","required":false,"description":"Set to \"true\" to preview the operation (validation, cost, plan) without making changes.","schema":{"type":"string","enum":["true","false"]}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Unique key for safe retries. Repeating a request with the same key returns the original response instead of re-executing.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"hostname":{"type":"string"},"index_url":{"type":"string","format":"uri"},"site_prompt":{"type":"string"}}}}}},"security":[{"agentCode":[]}]},"delete":{"operationId":"deleteAssistSite","summary":"Delete an Assist site","description":"The site's sitekey stops working immediately.","tags":["Assist"],"responses":{"200":{"description":"Success.","headers":{"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TellUserEnvelope"}}}},"400":{"description":"Validation error — the response body explains what to fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid agent access code. The body includes self-signup pointers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Honour Retry-After and the RateLimit-* headers before retrying.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Assist site id.","schema":{"type":"string"}},{"name":"X-Dry-Run","in":"header","required":false,"description":"Set to \"true\" to preview the operation (validation, cost, plan) without making changes.","schema":{"type":"string","enum":["true","false"]}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Unique key for safe retries. Repeating a request with the same key returns the original response instead of re-executing.","schema":{"type":"string"}}],"security":[{"agentCode":[]}]}},"/agent/assist/sites/{id}/reingest":{"post":{"operationId":"reingestAssistSite","summary":"Reingest an Assist site","description":"Fetch and index the site's content from its index_url now (also runs on an automatic refresh cycle). Returns page/chunk counts. Any reingest invalidates the answer cache.","tags":["Assist"],"responses":{"200":{"description":"Success.","headers":{"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TellUserEnvelope"}}}},"400":{"description":"Validation error — the response body explains what to fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid agent access code. The body includes self-signup pointers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Honour Retry-After and the RateLimit-* headers before retrying.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Assist site id.","schema":{"type":"string"}},{"name":"X-Dry-Run","in":"header","required":false,"description":"Set to \"true\" to preview the operation (validation, cost, plan) without making changes.","schema":{"type":"string","enum":["true","false"]}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Unique key for safe retries. Repeating a request with the same key returns the original response instead of re-executing.","schema":{"type":"string"}}],"security":[{"agentCode":[]}]}},"/agent/assist/sites/{id}/overview":{"get":{"operationId":"getAssistSiteOverview","summary":"Assist site usage and health","description":"Questions today/7d/30d, answer rate, cache hits, index freshness, cap consumption.","tags":["Assist"],"responses":{"200":{"description":"Success.","headers":{"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TellUserEnvelope"}}}},"400":{"description":"Validation error — the response body explains what to fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid agent access code. The body includes self-signup pointers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Honour Retry-After and the RateLimit-* headers before retrying.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Assist site id.","schema":{"type":"string"}}],"security":[{"agentCode":[]}]}},"/agent/assist/sites/{id}/questions":{"get":{"operationId":"listAssistQuestions","summary":"Assist question log","description":"What visitors actually asked. Filter with answered=false to find content gaps.","tags":["Assist"],"responses":{"200":{"description":"Success.","headers":{"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TellUserEnvelope"}}}},"400":{"description":"Validation error — the response body explains what to fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid agent access code. The body includes self-signup pointers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Honour Retry-After and the RateLimit-* headers before retrying.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-API-Version":{"$ref":"#/components/headers/XApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"description":"Assist site id.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Max entries to return.","schema":{"type":"integer","minimum":1,"maximum":500,"default":50}},{"name":"answered","in":"query","required":false,"description":"Filter by answered state. \"false\" surfaces unanswered questions.","schema":{"type":"string","enum":["true","false"]}}],"security":[{"agentCode":[]}]}}},"components":{"securitySchemes":{"agentCode":{"type":"http","scheme":"bearer","bearerFormat":"ea_live_...","description":"Agent access code. Get one from the Edge console (Account → Agent Access) or autonomously via GET /agent/signup. Public endpoints (discovery, prompt, signup) need no credentials."}},"schemas":{"TellUserEnvelope":{"type":"object","description":"Standard success envelope. Endpoint-specific fields ride alongside tell_user.","properties":{"tell_user":{"type":"string","description":"Human-readable summary of what happened, for the agent to relay to its operator."}},"additionalProperties":true,"required":["tell_user"]},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Machine-readable error code, e.g. VALIDATION_ERROR."},"message":{"type":"string","description":"What went wrong."},"suggestions":{"type":"array","items":{"type":"string"},"description":"Concrete next steps for the agent."},"tell_user":{"type":"string","description":"Plain-English summary to relay to the operator."}},"required":["code","message"]}},"required":["error"]},"Project":{"type":"object","properties":{"id":{"type":"string","description":"Project id, e.g. proj_ab12cd34."},"name":{"type":"string"},"description":{"type":"string","nullable":true},"resources":{"type":"array","description":"Resources grouped under this project.","items":{"type":"object","properties":{"type":{"type":"string","description":"Resource type, e.g. vm, bucket, cdn, dns_zone."},"id":{"type":"string"},"name":{"type":"string"}},"required":["type","id"]}},"created_at":{"type":"string","format":"date-time"}},"required":["id","name"]},"Vm":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","description":"Lifecycle status. Poll until \"running\" before attempting SSH."},"size":{"type":"string","enum":["nano","small","medium","large","xlarge"]},"vcpu":{"type":"number"},"ram":{"type":"number","description":"RAM in GB."},"disk":{"type":"number","description":"Disk in GB."},"region":{"type":"string"},"os":{"type":"string"},"network":{"type":"object","properties":{"publicIp":{"type":"string","nullable":true}}}},"required":["id","name","status"]},"DnsZone":{"type":"object","properties":{"id":{"type":"string"},"domain":{"type":"string"},"records":{"type":"array","items":{"$ref":"#/components/schemas/DnsRecord"}}},"required":["id","domain"]},"DnsRecord":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["A","AAAA","CNAME","MX","TXT","NS"]},"name":{"type":"string","description":"Record name, e.g. \"www\" or \"@\" for the zone root."},"data":{"type":"string","description":"Record value, e.g. an IP address or target hostname."},"ttl":{"type":"number"},"priority":{"type":"number","nullable":true,"description":"MX priority."}},"required":["type","name","data"]},"ShieldWidget":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"sitekey":{"type":"string","description":"Public sitekey used in the embed snippet."},"hostnames":{"type":"array","items":{"type":"string"}},"mode":{"type":"string","enum":["managed","non-interactive","invisible"]},"agent_policy":{"type":"string","enum":["allow","challenge","block"]}},"required":["id","name","sitekey"]},"AssistSite":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"hostname":{"type":"string","description":"Hostname the widget is origin-locked to."},"sitekey":{"type":"string"},"index_url":{"type":"string","nullable":true},"questions_this_month":{"type":"number"},"monthly_cap":{"type":"number","nullable":true}},"required":["id","name","hostname"]},"StorageBucket":{"type":"object","properties":{"name":{"type":"string"},"objects":{"type":"number"},"size_bytes":{"type":"number"},"created_at":{"type":"string","format":"date-time"}},"required":["name"]},"UploadFile":{"type":"object","properties":{"path":{"type":"string","description":"File path/key, e.g. \"index.html\" or \"assets/style.css\"."},"content":{"type":"string","description":"Base64-encoded file content."},"content_type":{"type":"string","description":"MIME type. Auto-detected from the extension if omitted."}},"required":["path","content"]},"SshKey":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"public_key":{"type":"string"},"created_at":{"type":"string","format":"date-time"}},"required":["id","name"]},"OsTemplate":{"type":"object","description":"Operating system template for VM creation.","properties":{"id":{"type":"string","description":"Template id to pass as \"os\" when creating a VM, e.g. ubuntu-24.04."},"name":{"type":"string"}},"required":["id"],"additionalProperties":true},"Region":{"type":"object","description":"Compute region available to this account.","properties":{"id":{"type":"string","description":"Region id to pass as \"region\" when creating a VM, e.g. london."},"name":{"type":"string"}},"required":["id"],"additionalProperties":true},"ComputeScript":{"type":"object","description":"Startup script (Edge library or custom) runnable on first boot.","properties":{"id":{"type":"string","description":"Script id to pass as \"script\" when creating a VM."},"name":{"type":"string"},"description":{"type":"string"},"category":{"type":"string"},"source":{"type":"string","enum":["edge-library","custom"]},"parameters":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"label":{"type":"string"},"type":{"type":"string"},"required":{"type":"boolean"},"default":{"description":"Default value, if any."}},"required":["name"]}}},"required":["id","name"]},"CdnDeployment":{"type":"object","description":"CDN deployment with its domains and origin configuration.","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"domains":{"type":"array","items":{"type":"object","additionalProperties":true}}},"required":["id"],"additionalProperties":true},"TestDomain":{"type":"object","description":"A registered test.network subdomain.","properties":{"id":{"type":"string"},"fullDomain":{"type":"string","description":"e.g. my-project.test.network."},"created_at":{"type":"string","format":"date-time"}},"required":["id"],"additionalProperties":true},"SecurityGroup":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"rules":{"type":"array","items":{"type":"object","properties":{"direction":{"type":"string","enum":["inbound","outbound"]},"protocol":{"type":"string","enum":["tcp","udp","icmp","all"]},"portRange":{"type":"string","description":"Port or range, e.g. \"80\" or \"8000-9000\". Omit for all ports."},"source":{"type":"string","description":"Source CIDR, e.g. 0.0.0.0/0."}}}}},"required":["id","name"]}},"headers":{"XApiVersion":{"description":"Current API major version. Breaking changes ship under a new URL prefix with Deprecation/Sunset headers on the old surface. See https://edge.network/docs/api/versioning.","schema":{"type":"string","example":"1"}},"RateLimitLimit":{"description":"Request quota for the current window (IETF draft-ietf-httpapi-ratelimit-headers).","schema":{"type":"integer"}},"RateLimitRemaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"RateLimitReset":{"description":"Seconds until the quota resets.","schema":{"type":"integer"}},"RateLimitPolicy":{"description":"Quota policy: \"<limit>;w=<window-seconds>\", e.g. \"600;w=60\".","schema":{"type":"string","example":"600;w=60"}},"RetryAfter":{"description":"Seconds to wait before retrying (sent with 429 responses).","schema":{"type":"integer"}}}}}