{"openapi":"3.1.0","info":{"title":"Zoophost Agent API","version":"2.1.0","summary":"Programmatic control of hosting, DNS, mail, storage and billing.","description":"Every endpoint is scoped to one workspace. Authenticate with an org API key\n(`Authorization: Bearer zp_live_…`); the key decides the workspace, so\n`X-Organization-Id` is ignored for key callers.\n\nGuardrails: reads run immediately; destructive and billing actions on a\nnon-auto-approve key return **202** with an approval id and change nothing\nuntil a human approves. Billing spend always requires approval.\n\nSend an `Idempotency-Key` on every mutating call — retries then replay the\noriginal result instead of duplicating work.","contact":{"name":"Zoophost","url":"https://zoophost.com"}},"servers":[{"url":"https://api.falcon.zoophost.com/api/v1","description":"Production"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Agent","description":"Discover your permissions, manage approvals."},{"name":"Sites","description":"Applications: deploy, restart, env vars, logs."},{"name":"Databases","description":"Managed database instances."},{"name":"Deployments","description":"Build history and running deploys."},{"name":"DNS","description":"Zones and records."},{"name":"Mail","description":"Mail domains and mailboxes."},{"name":"Storage","description":"Object storage buckets."},{"name":"Billing","description":"Invoices, subscriptions, wallet."}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"An org API key (`zp_live_<keyId>_<secret>`) or a console JWT. API keys are the intended path for agents."}},"schemas":{"Error":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. NO_WEBSITE_SLOTS."},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true},"hint":{"type":"string","description":"Short actionable sentence. Read this before retrying — it usually tells you what to change."},"requestId":{"type":"string"}},"required":["code","message"]},"timestamp":{"type":"string","format":"date-time"}},"required":["success","error"]},"ApprovalPending":{"type":"object","properties":{"status":{"type":"string","enum":["pending_approval"]},"approvalId":{"type":"string"},"kind":{"type":"string"},"method":{"type":"string"},"path":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"},"message":{"type":"string"},"pollUrl":{"type":"string"}}},"Approval":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"method":{"type":"string"},"path":{"type":"string"},"body":{},"status":{"type":"string","enum":["pending","approved","rejected","executing","completed","failed","expired"]},"apiKeyId":{"type":"string","nullable":true},"keyName":{"type":"string","nullable":true},"decidedAt":{"type":"string","format":"date-time","nullable":true},"resultSummary":{"type":"string","nullable":true},"error":{"type":"string","nullable":true},"expiresAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"}}},"Site":{"type":"object","properties":{"uuid":{"type":"string","description":"Provider resource id. Use it as the {uuid} path param."},"name":{"type":"string"},"type":{"type":"string","enum":["application","service","database"]},"status":{"type":"string","enum":["running","stopped","deploying","failed"]},"domains":{"type":"array","items":{"type":"string"}},"fqdn":{"type":"string","nullable":true},"projectUuid":{"type":"string","nullable":true},"lastDeployedAt":{"type":"string","format":"date-time","nullable":true},"billing":{"type":"object","nullable":true,"properties":{"serviceId":{"type":"string"},"subscriptionId":{"type":"string"},"planName":{"type":"string"},"planSku":{"type":"string"},"serviceStatus":{"type":"string"}}}}},"Deployment":{"type":"object","properties":{"uuid":{"type":"string"},"resourceUuid":{"type":"string"},"status":{"type":"string","enum":["queued","building","deploying","success","failed","cancelled"]},"createdAt":{"type":"string","format":"date-time"},"finishedAt":{"type":"string","format":"date-time","nullable":true},"logs":{"type":"array","items":{"type":"string"}}}},"DnsZone":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["mail","web","standalone"]},"provider":{"type":"string"},"mailEnabled":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"}}},"DnsRecord":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["A","AAAA","CNAME","MX","TXT","NS","SRV","CAA"]},"content":{"type":"string"},"ttl":{"type":"integer"},"priority":{"type":"integer","nullable":true}}},"Mailbox":{"type":"object","properties":{"id":{"type":"string"},"address":{"type":"string"},"displayName":{"type":"string","nullable":true},"quotaBytes":{"type":"integer","nullable":true},"status":{"type":"string"}}},"StorageService":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"planName":{"type":"string","nullable":true},"buckets":{"type":"array","items":{"$ref":"#/components/schemas/Bucket"}}}},"Bucket":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"quotaBytes":{"type":"integer","nullable":true},"objectCount":{"type":"integer","nullable":true}}},"ApiKey":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"keyId":{"type":"string"},"prefix":{"type":"string"},"scopes":{"type":"array","items":{"type":"string","enum":["site:read","site:deploy","site:write","site:delete","database:read","database:deploy","database:write","database:delete","deployment:read","deployment:write","dns:read","dns:write","mail:read","mail:write","storage:read","storage:write","billing:read","billing:spend","org:read","org:write"]}},"roleCap":{"type":"string","enum":["admin","developer","billing","viewer"]},"mode":{"type":"string","enum":["live","test"]},"autoApprove":{"type":"boolean"},"rateLimitPerMinute":{"type":"integer"},"monthlySpendCapMinor":{"type":"integer","nullable":true},"requestCount":{"type":"integer"},"lastUsedAt":{"type":"string","format":"date-time","nullable":true},"revokedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}}},"Manifest":{"type":"object","description":"What this credential may do, and what needs a human.","additionalProperties":true}}},"paths":{"/agent/manifest":{"get":{"tags":["Agent"],"summary":"Discover your own capabilities","description":"Call this first. Returns your effective scopes, the approval policy, and the endpoint for each capability — so you never have to probe until something 403s.","responses":{"200":{"description":"Capability manifest.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/Manifest"},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"timestamp":{"type":"string","format":"date-time"}},"required":["success","timestamp"]}}}},"401":{"description":"Missing or invalid credentials (JWT or API key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (role, scope, or spend cap).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-key rate limit exceeded. Honour `retryAfterSeconds`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/agent/whoami":{"get":{"tags":["Agent"],"summary":"Identity, workspace and remaining spend","responses":{"200":{"description":"Key identity plus `spend.spentThisMonthMinor` / `capMinor`.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"timestamp":{"type":"string","format":"date-time"}},"required":["success","timestamp"]}}}},"401":{"description":"Missing or invalid credentials (JWT or API key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (role, scope, or spend cap).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-key rate limit exceeded. Honour `retryAfterSeconds`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/agent/scopes":{"get":{"tags":["Agent"],"summary":"Scope catalogue","description":"The authoritative list of scopes, grouped, with which ones are approval-gated.","responses":{"200":{"description":"Scope catalogue.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"timestamp":{"type":"string","format":"date-time"}},"required":["success","timestamp"]}}}}}}},"/agent/approvals":{"get":{"tags":["Agent"],"summary":"List approval requests","parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["pending","completed","failed","rejected","expired","all"],"default":"pending"}},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":200}}],"responses":{"200":{"description":"Approval list.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Approval"}},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"timestamp":{"type":"string","format":"date-time"}},"required":["success","timestamp"]}}}},"401":{"description":"Missing or invalid credentials (JWT or API key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (role, scope, or spend cap).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-key rate limit exceeded. Honour `retryAfterSeconds`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/agent/approvals/{id}":{"get":{"tags":["Agent"],"summary":"Poll an approval","description":"Status flow: pending → executing → completed | failed. `rejected` and `expired` are terminal.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Approval.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/Approval"},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"timestamp":{"type":"string","format":"date-time"}},"required":["success","timestamp"]}}}},"401":{"description":"Missing or invalid credentials (JWT or API key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (role, scope, or spend cap).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown approval in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-key rate limit exceeded. Honour `retryAfterSeconds`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/websites":{"get":{"tags":["Sites"],"summary":"List sites","description":"Requires scope `site:read`.","responses":{"200":{"description":"Sites in this workspace.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Site"}},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"timestamp":{"type":"string","format":"date-time"}},"required":["success","timestamp"]}}}},"401":{"description":"Missing or invalid credentials (JWT or API key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (role, scope, or spend cap).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-key rate limit exceeded. Honour `retryAfterSeconds`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/websites/{uuid}":{"get":{"tags":["Sites"],"summary":"Get one site","parameters":[{"name":"uuid","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Site.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/Site"},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"timestamp":{"type":"string","format":"date-time"}},"required":["success","timestamp"]}}}},"401":{"description":"Missing or invalid credentials (JWT or API key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (role, scope, or spend cap).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-key rate limit exceeded. Honour `retryAfterSeconds`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Sites"],"summary":"Delete a site","description":"Requires `site:delete`. On a key without auto-approve this returns 202 and changes nothing until approved.","parameters":[{"name":"uuid","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. Repeating a mutating request with the same key replays the first response instead of acting twice. Reusing a key with a different body returns 422.","schema":{"type":"string","maxLength":200}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional correlation id, echoed in the response and in audit rows.","schema":{"type":"string","maxLength":128}}],"responses":{"200":{"description":"Deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"timestamp":{"type":"string","format":"date-time"}},"required":["success","timestamp"]}}}},"202":{"description":"Queued for human approval. No state was changed. Poll `pollUrl` (or `GET /agent/approvals/{id}`) until the status settles.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/ApprovalPending"},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"timestamp":{"type":"string","format":"date-time"}},"required":["success","timestamp"]}}}},"401":{"description":"Missing or invalid credentials (JWT or API key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (role, scope, or spend cap).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-key rate limit exceeded. Honour `retryAfterSeconds`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/websites/provision":{"post":{"tags":["Sites"],"summary":"Deploy a new site against plan slots","description":"Requires `site:deploy`. Consumes one website slot from an active Cloud Hosting plan; no payment is taken. Fails with 403 `NO_WEBSITE_SLOTS` when the workspace has none left.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. Repeating a mutating request with the same key replays the first response instead of acting twice. Reusing a key with a different body returns 422.","schema":{"type":"string","maxLength":200}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional correlation id, echoed in the response and in audit rows.","schema":{"type":"string","maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"subscriptionId":{"type":"string","description":"Draw from a specific plan; omit for any with a free slot."},"options":{"type":"object","description":"Deployment source. One of gitRepository, dockerImage, dockerfile URL, or serviceType (one-click compose).","properties":{"name":{"type":"string"},"gitRepository":{"type":"string"},"gitBranch":{"type":"string"},"buildPack":{"type":"string","enum":["nixpacks","railpack","static","dockerfile","dockercompose"]},"dockerImage":{"type":"string"},"dockerfile":{"type":"string"},"domains":{"type":"string","description":"Comma-separated hostnames."},"portsExposes":{"type":"string"}}}},"required":["options"]}}}},"responses":{"201":{"description":"`{ serviceId, uuid, planName, balance }`.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"timestamp":{"type":"string","format":"date-time"}},"required":["success","timestamp"]}}}},"401":{"description":"Missing or invalid credentials (JWT or API key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (role, scope, or spend cap).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Another deploy took the last slot (`QUOTA_EXCEEDED`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-key rate limit exceeded. Honour `retryAfterSeconds`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Provider could not create the app (`PROVISIONING_FAILED`, includes `serviceId`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/websites/{uuid}/deploy":{"post":{"tags":["Sites"],"summary":"Trigger a deploy","description":"Requires `site:deploy`. Returns immediately; the build runs async. Poll `/deployments/{uuid}` for progress.","parameters":[{"name":"uuid","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. Repeating a mutating request with the same key replays the first response instead of acting twice. Reusing a key with a different body returns 422.","schema":{"type":"string","maxLength":200}}],"responses":{"200":{"description":"Deploy queued.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"timestamp":{"type":"string","format":"date-time"}},"required":["success","timestamp"]}}}},"401":{"description":"Missing or invalid credentials (JWT or API key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (role, scope, or spend cap).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-key rate limit exceeded. Honour `retryAfterSeconds`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/websites/{uuid}/restart":{"post":{"tags":["Sites"],"summary":"Restart a site","parameters":[{"name":"uuid","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. Repeating a mutating request with the same key replays the first response instead of acting twice. Reusing a key with a different body returns 422.","schema":{"type":"string","maxLength":200}}],"responses":{"200":{"description":"Restarted.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"timestamp":{"type":"string","format":"date-time"}},"required":["success","timestamp"]}}}},"401":{"description":"Missing or invalid credentials (JWT or API key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (role, scope, or spend cap).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-key rate limit exceeded. Honour `retryAfterSeconds`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/websites/{uuid}/stop":{"post":{"tags":["Sites"],"summary":"Stop a site","parameters":[{"name":"uuid","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. Repeating a mutating request with the same key replays the first response instead of acting twice. Reusing a key with a different body returns 422.","schema":{"type":"string","maxLength":200}}],"responses":{"200":{"description":"Stopped.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"timestamp":{"type":"string","format":"date-time"}},"required":["success","timestamp"]}}}},"401":{"description":"Missing or invalid credentials (JWT or API key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (role, scope, or spend cap).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-key rate limit exceeded. Honour `retryAfterSeconds`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/websites/{uuid}/start":{"post":{"tags":["Sites"],"summary":"Start a site","parameters":[{"name":"uuid","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. Repeating a mutating request with the same key replays the first response instead of acting twice. Reusing a key with a different body returns 422.","schema":{"type":"string","maxLength":200}}],"responses":{"200":{"description":"Started.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"timestamp":{"type":"string","format":"date-time"}},"required":["success","timestamp"]}}}},"401":{"description":"Missing or invalid credentials (JWT or API key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (role, scope, or spend cap).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-key rate limit exceeded. Honour `retryAfterSeconds`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/websites/{uuid}/envs":{"get":{"tags":["Sites"],"summary":"List environment variables","parameters":[{"name":"uuid","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Env variable list.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"timestamp":{"type":"string","format":"date-time"}},"required":["success","timestamp"]}}}},"401":{"description":"Missing or invalid credentials (JWT or API key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (role, scope, or spend cap).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-key rate limit exceeded. Honour `retryAfterSeconds`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"tags":["Sites"],"summary":"Replace environment variables","description":"Requires `site:write`. Sending the full set replaces existing keys.","parameters":[{"name":"uuid","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. Repeating a mutating request with the same key replays the first response instead of acting twice. Reusing a key with a different body returns 422.","schema":{"type":"string","maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"envs":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"},"isPreview":{"type":"boolean"}},"required":["key","value"]}}},"required":["envs"]}}}},"responses":{"200":{"description":"Env variables replaced.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"timestamp":{"type":"string","format":"date-time"}},"required":["success","timestamp"]}}}},"401":{"description":"Missing or invalid credentials (JWT or API key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (role, scope, or spend cap).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-key rate limit exceeded. Honour `retryAfterSeconds`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/websites/{uuid}/logs":{"get":{"tags":["Sites"],"summary":"Runtime logs","parameters":[{"name":"uuid","in":"path","required":true,"schema":{"type":"string"}},{"name":"lines","in":"query","schema":{"type":"integer","default":100,"maximum":1000}}],"responses":{"200":{"description":"Log lines.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"timestamp":{"type":"string","format":"date-time"}},"required":["success","timestamp"]}}}},"401":{"description":"Missing or invalid credentials (JWT or API key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (role, scope, or spend cap).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-key rate limit exceeded. Honour `retryAfterSeconds`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/websites/plan-balance":{"get":{"tags":["Sites"],"summary":"Remaining website slots per plan","responses":{"200":{"description":"Slot pools: `{ pools, usedSlots, limitOverride }`.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"timestamp":{"type":"string","format":"date-time"}},"required":["success","timestamp"]}}}},"401":{"description":"Missing or invalid credentials (JWT or API key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (role, scope, or spend cap).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-key rate limit exceeded. Honour `retryAfterSeconds`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/databases":{"get":{"tags":["Databases"],"summary":"List databases","responses":{"200":{"description":"Database instances.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"timestamp":{"type":"string","format":"date-time"}},"required":["success","timestamp"]}}}},"401":{"description":"Missing or invalid credentials (JWT or API key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (role, scope, or spend cap).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-key rate limit exceeded. Honour `retryAfterSeconds`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/databases/provision":{"post":{"tags":["Databases"],"summary":"Provision a database against plan slots","description":"Requires `database:deploy`. 403 `NO_DATABASE_SLOTS` when the workspace has no free slot.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. Repeating a mutating request with the same key replays the first response instead of acting twice. Reusing a key with a different body returns 422.","schema":{"type":"string","maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"subscriptionId":{"type":"string"},"options":{"type":"object","properties":{"name":{"type":"string"},"engine":{"type":"string","enum":["postgresql","mysql","mariadb","mongodb","redis","keydb","dragonfly","clickhouse"]}}}}}}}},"responses":{"201":{"description":"`{ serviceId, uuid, planName, balance }`.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"timestamp":{"type":"string","format":"date-time"}},"required":["success","timestamp"]}}}},"401":{"description":"Missing or invalid credentials (JWT or API key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (role, scope, or spend cap).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-key rate limit exceeded. Honour `retryAfterSeconds`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/databases/{uuid}":{"get":{"tags":["Databases"],"summary":"Get a database","parameters":[{"name":"uuid","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Database.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"timestamp":{"type":"string","format":"date-time"}},"required":["success","timestamp"]}}}},"401":{"description":"Missing or invalid credentials (JWT or API key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (role, scope, or spend cap).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-key rate limit exceeded. Honour `retryAfterSeconds`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Databases"],"summary":"Delete a database","description":"Requires `database:delete`. Approval-gated on non-auto-approve keys.","parameters":[{"name":"uuid","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. Repeating a mutating request with the same key replays the first response instead of acting twice. Reusing a key with a different body returns 422.","schema":{"type":"string","maxLength":200}}],"responses":{"200":{"description":"Deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"timestamp":{"type":"string","format":"date-time"}},"required":["success","timestamp"]}}}},"202":{"description":"Queued for human approval. No state was changed. Poll `pollUrl` (or `GET /agent/approvals/{id}`) until the status settles.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/ApprovalPending"},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"timestamp":{"type":"string","format":"date-time"}},"required":["success","timestamp"]}}}},"401":{"description":"Missing or invalid credentials (JWT or API key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (role, scope, or spend cap).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-key rate limit exceeded. Honour `retryAfterSeconds`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/databases/{uuid}/logs":{"get":{"tags":["Databases"],"summary":"Database logs","parameters":[{"name":"uuid","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Log lines.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"timestamp":{"type":"string","format":"date-time"}},"required":["success","timestamp"]}}}},"401":{"description":"Missing or invalid credentials (JWT or API key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (role, scope, or spend cap).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-key rate limit exceeded. Honour `retryAfterSeconds`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/deployments":{"get":{"tags":["Deployments"],"summary":"Recent builds across this workspace","description":"Requires `deployment:read`. Covers every owned resource, newest first.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":100,"maximum":100}}],"responses":{"200":{"description":"Deployments.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Deployment"}},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"timestamp":{"type":"string","format":"date-time"}},"required":["success","timestamp"]}}}},"401":{"description":"Missing or invalid credentials (JWT or API key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (role, scope, or spend cap).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-key rate limit exceeded. Honour `retryAfterSeconds`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/deployments/{uuid}":{"get":{"tags":["Deployments"],"summary":"One deployment with build logs","description":"Poll this after triggering a deploy. `status` is normalized to queued|building|deploying|success|failed|cancelled.","parameters":[{"name":"uuid","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deployment.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/Deployment"},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"timestamp":{"type":"string","format":"date-time"}},"required":["success","timestamp"]}}}},"401":{"description":"Missing or invalid credentials (JWT or API key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (role, scope, or spend cap).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-key rate limit exceeded. Honour `retryAfterSeconds`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/deployments/{uuid}/cancel":{"post":{"tags":["Deployments"],"summary":"Cancel a running deployment","parameters":[{"name":"uuid","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. Repeating a mutating request with the same key replays the first response instead of acting twice. Reusing a key with a different body returns 422.","schema":{"type":"string","maxLength":200}}],"responses":{"200":{"description":"Cancelled.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"timestamp":{"type":"string","format":"date-time"}},"required":["success","timestamp"]}}}},"401":{"description":"Missing or invalid credentials (JWT or API key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (role, scope, or spend cap).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-key rate limit exceeded. Honour `retryAfterSeconds`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/dns":{"get":{"tags":["DNS"],"summary":"List zones and zone entitlement","responses":{"200":{"description":"Zones plus remaining capacity.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"timestamp":{"type":"string","format":"date-time"}},"required":["success","timestamp"]}}}},"401":{"description":"Missing or invalid credentials (JWT or API key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (role, scope, or spend cap).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-key rate limit exceeded. Honour `retryAfterSeconds`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["DNS"],"summary":"Create a zone","description":"Requires `dns:write`. Publishes default A/CNAME records and mail records.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. Repeating a mutating request with the same key replays the first response instead of acting twice. Reusing a key with a different body returns 422.","schema":{"type":"string","maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","example":"example.com"}},"required":["name"]}}}},"responses":{"201":{"description":"Created zone.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/DnsZone"},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"timestamp":{"type":"string","format":"date-time"}},"required":["success","timestamp"]}}}},"401":{"description":"Missing or invalid credentials (JWT or API key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (role, scope, or spend cap).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Zone already exists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-key rate limit exceeded. Honour `retryAfterSeconds`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/dns/{id}":{"get":{"tags":["DNS"],"summary":"Get a zone with its records","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Zone.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/DnsZone"},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"timestamp":{"type":"string","format":"date-time"}},"required":["success","timestamp"]}}}},"401":{"description":"Missing or invalid credentials (JWT or API key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (role, scope, or spend cap).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-key rate limit exceeded. Honour `retryAfterSeconds`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["DNS"],"summary":"Delete a zone","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. Repeating a mutating request with the same key replays the first response instead of acting twice. Reusing a key with a different body returns 422.","schema":{"type":"string","maxLength":200}}],"responses":{"200":{"description":"Deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"timestamp":{"type":"string","format":"date-time"}},"required":["success","timestamp"]}}}},"401":{"description":"Missing or invalid credentials (JWT or API key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (role, scope, or spend cap).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-key rate limit exceeded. Honour `retryAfterSeconds`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/dns/{id}/records":{"get":{"tags":["DNS"],"summary":"List records","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Records.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/DnsRecord"}},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"timestamp":{"type":"string","format":"date-time"}},"required":["success","timestamp"]}}}},"401":{"description":"Missing or invalid credentials (JWT or API key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (role, scope, or spend cap).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-key rate limit exceeded. Honour `retryAfterSeconds`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["DNS"],"summary":"Add a record","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. Repeating a mutating request with the same key replays the first response instead of acting twice. Reusing a key with a different body returns 422.","schema":{"type":"string","maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","example":"www"},"type":{"type":"string","enum":["A","AAAA","CNAME","MX","TXT","NS","SRV","CAA"]},"content":{"type":"string"},"ttl":{"type":"integer","default":300},"priority":{"type":"integer"}},"required":["type","content"]}}}},"responses":{"201":{"description":"Created record.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/DnsRecord"},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"timestamp":{"type":"string","format":"date-time"}},"required":["success","timestamp"]}}}},"401":{"description":"Missing or invalid credentials (JWT or API key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (role, scope, or spend cap).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-key rate limit exceeded. Honour `retryAfterSeconds`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/dns/{id}/records/{recordId}":{"put":{"tags":["DNS"],"summary":"Update a record","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"recordId","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. Repeating a mutating request with the same key replays the first response instead of acting twice. Reusing a key with a different body returns 422.","schema":{"type":"string","maxLength":200}}],"responses":{"200":{"description":"Updated.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"timestamp":{"type":"string","format":"date-time"}},"required":["success","timestamp"]}}}},"401":{"description":"Missing or invalid credentials (JWT or API key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (role, scope, or spend cap).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-key rate limit exceeded. Honour `retryAfterSeconds`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["DNS"],"summary":"Delete a record","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"recordId","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. Repeating a mutating request with the same key replays the first response instead of acting twice. Reusing a key with a different body returns 422.","schema":{"type":"string","maxLength":200}}],"responses":{"200":{"description":"Deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"timestamp":{"type":"string","format":"date-time"}},"required":["success","timestamp"]}}}},"401":{"description":"Missing or invalid credentials (JWT or API key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (role, scope, or spend cap).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-key rate limit exceeded. Honour `retryAfterSeconds`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/mail":{"get":{"tags":["Mail"],"summary":"Mail overview: domains, mailbox capacity","responses":{"200":{"description":"Domains plus slot usage.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"timestamp":{"type":"string","format":"date-time"}},"required":["success","timestamp"]}}}},"401":{"description":"Missing or invalid credentials (JWT or API key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (role, scope, or spend cap).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-key rate limit exceeded. Honour `retryAfterSeconds`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/mail/domains/{id}/mailboxes":{"get":{"tags":["Mail"],"summary":"List mailboxes on a domain","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Mailboxes.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Mailbox"}},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"timestamp":{"type":"string","format":"date-time"}},"required":["success","timestamp"]}}}},"401":{"description":"Missing or invalid credentials (JWT or API key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (role, scope, or spend cap).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-key rate limit exceeded. Honour `retryAfterSeconds`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Mail"],"summary":"Create a mailbox","description":"Requires `mail:write`. The generated password is returned once. 403 `QUOTA_EXCEEDED` when every mailbox slot is taken.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. Repeating a mutating request with the same key replays the first response instead of acting twice. Reusing a key with a different body returns 422.","schema":{"type":"string","maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"localPart":{"type":"string","description":"Lowercase; the part before @."},"password":{"type":"string","description":"Omit to auto-generate."},"displayName":{"type":"string"}},"required":["localPart"]}}}},"responses":{"201":{"description":"`{ mailbox, password }` — password is shown only here.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"timestamp":{"type":"string","format":"date-time"}},"required":["success","timestamp"]}}}},"401":{"description":"Missing or invalid credentials (JWT or API key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (role, scope, or spend cap).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Address already exists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-key rate limit exceeded. Honour `retryAfterSeconds`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/mail/mailboxes/{id}/password":{"post":{"tags":["Mail"],"summary":"Reset a mailbox password","description":"Requires `mail:write`. Approval-gated on non-auto-approve keys.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. Repeating a mutating request with the same key replays the first response instead of acting twice. Reusing a key with a different body returns 422.","schema":{"type":"string","maxLength":200}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"password":{"type":"string"}}}}}},"responses":{"200":{"description":"New password.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"timestamp":{"type":"string","format":"date-time"}},"required":["success","timestamp"]}}}},"202":{"description":"Queued for human approval. No state was changed. Poll `pollUrl` (or `GET /agent/approvals/{id}`) until the status settles.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/ApprovalPending"},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"timestamp":{"type":"string","format":"date-time"}},"required":["success","timestamp"]}}}},"401":{"description":"Missing or invalid credentials (JWT or API key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (role, scope, or spend cap).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-key rate limit exceeded. Honour `retryAfterSeconds`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/storage":{"get":{"tags":["Storage"],"summary":"List storage services","responses":{"200":{"description":"Services.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/StorageService"}},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"timestamp":{"type":"string","format":"date-time"}},"required":["success","timestamp"]}}}},"401":{"description":"Missing or invalid credentials (JWT or API key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (role, scope, or spend cap).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-key rate limit exceeded. Honour `retryAfterSeconds`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/storage/{id}":{"get":{"tags":["Storage"],"summary":"Storage service with credentials and buckets","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Service.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/StorageService"},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"timestamp":{"type":"string","format":"date-time"}},"required":["success","timestamp"]}}}},"401":{"description":"Missing or invalid credentials (JWT or API key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (role, scope, or spend cap).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-key rate limit exceeded. Honour `retryAfterSeconds`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/storage/{id}/buckets":{"post":{"tags":["Storage"],"summary":"Create a bucket","description":"Requires `storage:write`. Approval-gated on non-auto-approve keys.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. Repeating a mutating request with the same key replays the first response instead of acting twice. Reusing a key with a different body returns 422.","schema":{"type":"string","maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"3-63 lowercase letters, digits or hyphens."}},"required":["name"]}}}},"responses":{"201":{"description":"Created bucket.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/Bucket"},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"timestamp":{"type":"string","format":"date-time"}},"required":["success","timestamp"]}}}},"202":{"description":"Queued for human approval. No state was changed. Poll `pollUrl` (or `GET /agent/approvals/{id}`) until the status settles.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/ApprovalPending"},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"timestamp":{"type":"string","format":"date-time"}},"required":["success","timestamp"]}}}},"401":{"description":"Missing or invalid credentials (JWT or API key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (role, scope, or spend cap).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-key rate limit exceeded. Honour `retryAfterSeconds`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/storage/{id}/buckets/{bucketId}/upload-url":{"post":{"tags":["Storage"],"summary":"Presigned upload URL","description":"Requires `storage:write`. PUT the file body to the returned URL; no credentials needed.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"bucketId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string"},"size":{"type":"integer"},"contentType":{"type":"string"}},"required":["key","size"]}}}},"responses":{"200":{"description":"`{ url, method, headers, expiresAt }`.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"timestamp":{"type":"string","format":"date-time"}},"required":["success","timestamp"]}}}},"401":{"description":"Missing or invalid credentials (JWT or API key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (role, scope, or spend cap).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-key rate limit exceeded. Honour `retryAfterSeconds`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/storage/{id}/buckets/{bucketId}/download-url":{"post":{"tags":["Storage"],"summary":"Presigned download URL","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"bucketId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string"}},"required":["key"]}}}},"responses":{"200":{"description":"`{ url, expiresAt }`.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"timestamp":{"type":"string","format":"date-time"}},"required":["success","timestamp"]}}}},"401":{"description":"Missing or invalid credentials (JWT or API key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (role, scope, or spend cap).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-key rate limit exceeded. Honour `retryAfterSeconds`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/billing/services":{"get":{"tags":["Billing"],"summary":"Purchased services with subscription state","responses":{"200":{"description":"Provisioned services.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"timestamp":{"type":"string","format":"date-time"}},"required":["success","timestamp"]}}}},"401":{"description":"Missing or invalid credentials (JWT or API key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (role, scope, or spend cap).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-key rate limit exceeded. Honour `retryAfterSeconds`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/billing/invoices":{"get":{"tags":["Billing"],"summary":"List invoices","responses":{"200":{"description":"Invoices.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"timestamp":{"type":"string","format":"date-time"}},"required":["success","timestamp"]}}}},"401":{"description":"Missing or invalid credentials (JWT or API key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (role, scope, or spend cap).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-key rate limit exceeded. Honour `retryAfterSeconds`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/billing/subscriptions":{"get":{"tags":["Billing"],"summary":"List subscriptions","responses":{"200":{"description":"Subscriptions.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"timestamp":{"type":"string","format":"date-time"}},"required":["success","timestamp"]}}}},"401":{"description":"Missing or invalid credentials (JWT or API key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (role, scope, or spend cap).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-key rate limit exceeded. Honour `retryAfterSeconds`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/billing/wallet":{"get":{"tags":["Billing"],"summary":"Wallet balance","responses":{"200":{"description":"`{ balanceMinor, currency }`.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"timestamp":{"type":"string","format":"date-time"}},"required":["success","timestamp"]}}}},"401":{"description":"Missing or invalid credentials (JWT or API key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (role, scope, or spend cap).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-key rate limit exceeded. Honour `retryAfterSeconds`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/billing/checkout":{"post":{"tags":["Billing"],"summary":"Order a plan","description":"Requires `billing:spend`. **Always** requires human approval, even on auto-approve keys. Also bounded by the key monthly spend cap (`403 SPEND_CAP_EXCEEDED`).","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. Repeating a mutating request with the same key replays the first response instead of acting twice. Reusing a key with a different body returns 422.","schema":{"type":"string","maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"planId":{"type":"string"},"currency":{"type":"string","enum":["INR","USD"]},"couponCode":{"type":"string"},"paymentMethod":{"type":"string","enum":["wallet","gateway"]},"returnTo":{"type":"string","enum":["console","storefront"]}},"required":["planId"]}}}},"responses":{"200":{"description":"`{ invoiceId, gatewayOrderId, ... }`.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"timestamp":{"type":"string","format":"date-time"}},"required":["success","timestamp"]}}}},"202":{"description":"Queued for human approval. No state was changed. Poll `pollUrl` (or `GET /agent/approvals/{id}`) until the status settles.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/ApprovalPending"},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"timestamp":{"type":"string","format":"date-time"}},"required":["success","timestamp"]}}}},"401":{"description":"Missing or invalid credentials (JWT or API key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (role, scope, or spend cap).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-key rate limit exceeded. Honour `retryAfterSeconds`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/billing/cart/checkout":{"post":{"tags":["Billing"],"summary":"Multi-item order","description":"Requires `billing:spend`. Always requires approval.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. Repeating a mutating request with the same key replays the first response instead of acting twice. Reusing a key with a different body returns 422.","schema":{"type":"string","maxLength":200}}],"responses":{"202":{"description":"Queued for human approval. No state was changed. Poll `pollUrl` (or `GET /agent/approvals/{id}`) until the status settles.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/ApprovalPending"},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"timestamp":{"type":"string","format":"date-time"}},"required":["success","timestamp"]}}}},"401":{"description":"Missing or invalid credentials (JWT or API key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (role, scope, or spend cap).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-key rate limit exceeded. Honour `retryAfterSeconds`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/billing/invoices/{id}/pay":{"post":{"tags":["Billing"],"summary":"Pay an open invoice","description":"Requires `billing:spend`. Always requires approval.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. Repeating a mutating request with the same key replays the first response instead of acting twice. Reusing a key with a different body returns 422.","schema":{"type":"string","maxLength":200}}],"responses":{"202":{"description":"Queued for human approval. No state was changed. Poll `pollUrl` (or `GET /agent/approvals/{id}`) until the status settles.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/ApprovalPending"},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"timestamp":{"type":"string","format":"date-time"}},"required":["success","timestamp"]}}}},"401":{"description":"Missing or invalid credentials (JWT or API key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (role, scope, or spend cap).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-key rate limit exceeded. Honour `retryAfterSeconds`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/billing/wallet/topup":{"post":{"tags":["Billing"],"summary":"Top up the wallet","description":"Requires `billing:spend`. Always requires approval.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. Repeating a mutating request with the same key replays the first response instead of acting twice. Reusing a key with a different body returns 422.","schema":{"type":"string","maxLength":200}}],"responses":{"202":{"description":"Queued for human approval. No state was changed. Poll `pollUrl` (or `GET /agent/approvals/{id}`) until the status settles.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/ApprovalPending"},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"timestamp":{"type":"string","format":"date-time"}},"required":["success","timestamp"]}}}},"401":{"description":"Missing or invalid credentials (JWT or API key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (role, scope, or spend cap).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-key rate limit exceeded. Honour `retryAfterSeconds`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/billing/subscriptions/{id}/cancel":{"post":{"tags":["Billing"],"summary":"Cancel a subscription","description":"Requires `billing:spend`. Always requires approval.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. Repeating a mutating request with the same key replays the first response instead of acting twice. Reusing a key with a different body returns 422.","schema":{"type":"string","maxLength":200}}],"responses":{"202":{"description":"Queued for human approval. No state was changed. Poll `pollUrl` (or `GET /agent/approvals/{id}`) until the status settles.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/ApprovalPending"},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"timestamp":{"type":"string","format":"date-time"}},"required":["success","timestamp"]}}}},"401":{"description":"Missing or invalid credentials (JWT or API key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (role, scope, or spend cap).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-key rate limit exceeded. Honour `retryAfterSeconds`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/agent/keys":{"get":{"tags":["Agent"],"summary":"List API keys (human session only)","description":"An API key cannot manage keys — this route requires a console JWT.","responses":{"200":{"description":"Keys.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/ApiKey"}},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"timestamp":{"type":"string","format":"date-time"}},"required":["success","timestamp"]}}}},"401":{"description":"Missing or invalid credentials (JWT or API key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (role, scope, or spend cap).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-key rate limit exceeded. Honour `retryAfterSeconds`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Agent"],"summary":"Mint an API key (human session only)","description":"The plaintext token is returned once in `data.token` and never again. Scopes you cannot grant yourself are refused with 403 `SCOPE_NOT_PERMITTED`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":80},"scopes":{"type":"array","items":{"type":"string","enum":["site:read","site:deploy","site:write","site:delete","database:read","database:deploy","database:write","database:delete","deployment:read","deployment:write","dns:read","dns:write","mail:read","mail:write","storage:read","storage:write","billing:read","billing:spend","org:read","org:write"]},"minItems":1},"roleCap":{"type":"string","enum":["admin","developer","billing","viewer"]},"mode":{"type":"string","enum":["live","test"]},"autoApprove":{"type":"boolean","default":false},"rateLimitPerMinute":{"type":"integer","default":120},"monthlySpendCapMinor":{"type":"integer","nullable":true},"expiresAt":{"type":"string","format":"date-time","nullable":true}},"required":["name","scopes","roleCap"]}}}},"responses":{"201":{"description":"`{ key, token, notice }`.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"timestamp":{"type":"string","format":"date-time"}},"required":["success","timestamp"]}}}},"401":{"description":"Missing or invalid credentials (JWT or API key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (role, scope, or spend cap).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-key rate limit exceeded. Honour `retryAfterSeconds`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}