# Zoophost Agent API Zoophost is a hosting platform. This API lets a program provision and operate a single workspace's sites, databases, DNS, mail, object storage and billing. Base URL: https://api.falcon.zoophost.com/api/v1 Full spec: /api/docs/openapi.json ## Authentication Send the workspace API key as a bearer token: Authorization: Bearer zp_live__ The key determines the workspace. Do NOT send X-Organization-Id with a key — it is ignored. Keys are minted in Console -> Settings -> API keys and shown once. ## Before you act GET /agent/manifest Returns your effective scopes, the guardrail policy, and the endpoint for each capability. Do this instead of probing endpoints until something returns 403. ## Guardrails - Reads always run immediately. - Destructive actions (delete site/database, delete objects, reset a password, change DNS/mail settings) run immediately only if the key has auto-approve. Otherwise they return HTTP 202 with an approvalId and change NOTHING. - Billing spend ALWAYS needs human approval, regardless of auto-approve. - Every key has a monthly spend cap; exceeding it returns 403 SPEND_CAP_EXCEEDED. When you get a 202, tell the human the approvalId and poll: GET /agent/approvals/{approvalId} until status is completed, failed, rejected or expired. ## Idempotency Send `Idempotency-Key: ` on every POST/PUT/PATCH/DELETE. A retry with the same key and body replays the original response; the same key with a different body returns 422. Generate a new key per logical operation, and REUSE it when retrying that operation. ## Errors { "success": false, "error": { "code", "message", "details", "hint", "requestId" } } Always read `hint` before retrying — it usually says what to change. Quote `requestId` when reporting a problem. 429 means slow down; honour `details.retryAfterSeconds`. ## Status values - Site status: running | stopped | deploying | failed - Deployment status: queued | building | deploying | success | failed | cancelled - Approval status: pending | executing | completed | failed | rejected | expired Deploys are asynchronous: POST /websites/{uuid}/deploy returns immediately, then poll GET /deployments/{uuid}. ## Scopes ### Sites — Deploy and operate applications. - `site:read` — List and inspect sites, logs, env vars - `site:deploy` — Create a site, deploy, restart, start/stop - `site:write` — Change env vars, config, domains, cron tasks - `site:delete` _(approval-gated)_ — Delete a site ### Databases — Managed database instances. - `database:read` — List and inspect databases, logs, backups - `database:deploy` — Provision a database, start/stop/restart, back up - `database:write` — Change database configuration - `database:delete` _(approval-gated)_ — Delete a database ### Deployments — Build history and running deploys. - `deployment:read` — Read deployment history and build logs - `deployment:write` — Cancel a running deployment ### DNS — Zones and records. - `dns:read` — List zones and records - `dns:write` — Create zones, add/update/delete records ### Mail — Mail domains and mailboxes. - `mail:read` — List mail domains and mailboxes - `mail:write` — Create mailboxes, reset passwords, suspend ### Storage — Object storage buckets. - `storage:read` — List buckets and objects, presign downloads - `storage:write` _(approval-gated)_ — Create buckets, upload, delete objects, rotate keys ### Billing — Money. Spending always requires human approval. - `billing:read` — Read invoices, subscriptions, wallet balance - `billing:spend` _(approval-gated)_ — Checkout, pay invoices, top up wallet ### Workspace — Workspace settings and members. - `org:read` — Read workspace settings and members - `org:write` _(approval-gated)_ — Change workspace settings ## Typical flows Deploy this repo: 1. GET /agent/manifest 2. GET /websites/plan-balance (confirm a free slot) 3. POST /websites/provision { options: { name, gitRepository, gitBranch, buildPack } } 4. GET /websites/{uuid} until status is running 5. GET /deployments to follow the build Add a DNS record: 1. GET /dns (find the zone id) 2. POST /dns/{id}/records { name, type, content, ttl } Buy a plan (needs approval): 1. POST /billing/checkout -> 202 + approvalId 2. Tell the human; poll GET /agent/approvals/{approvalId}