ZoophostDocs

API overview

Authenticate with an API key, call the REST API, and understand the guardrails that protect destructive and billing actions.

API & agents3 min read

The Zoophost API lets a program — a CI job, a script, or an AI agent — manage your workspace. Every endpoint is scoped to a single workspace.

Get a key

Console → Settings → API keys → New key.

Choose the scopes the caller needs, pick a role cap, and decide whether it may auto-approve destructive actions. The token is shown once; after that the panel only stores a hash, so a lost key is rotated rather than recovered.

Tokens look like zp_live_<keyId>_<secret>.

Make a request

curl https://api.falcon.zoophost.com/api/v1/websites \
  -H "Authorization: Bearer zp_live_xxxxxxxx_yyyyyyyyyyyyyyyyyyyyyyyy"

The key determines the workspace. Do not send an X-Organization-Id header with a key — it is ignored.

Responses use one envelope:

{ "success": true, "data": { }, "timestamp": "2026-11-16T10:00:00.000Z" }

Errors use the same shape, with an actionable hint:

{
  "success": false,
  "error": {
    "code": "NO_WEBSITE_SLOTS",
    "message": "No free website slot on this workspace's plans",
    "hint": "Order a Cloud Hosting plan, or free a slot by deleting a site.",
    "requestId": "5f3c…"
  },
  "timestamp": "2026-11-16T10:00:00.000Z"
}

Read hint before retrying — it usually says what to change. Quote requestId when reporting a problem.

Start here

Call GET /api/v1/agent/manifest. It returns the scopes your key actually has, the approval policy in force, and the endpoint for each capability. Probing endpoints until one returns 403 is slower and tells you less.

Guardrails

Action class Behaviour
Reads Always run immediately.
Deploys, restarts, env changes Run immediately.
Deletes, password resets, DNS/mail/storage changes Run immediately only on an auto-approve key; otherwise queued for a human.
Billing spend Always queued for a human, even on auto-approve keys.

A queued action returns HTTP 202 and changes nothing:

{
  "success": true,
  "data": {
    "status": "pending_approval",
    "approvalId": "68f…",
    "pollUrl": "/api/v1/agent/approvals/68f…",
    "message": "This action needs a human to approve it."
  }
}

Approve or reject it in Console → Settings → Agent approvals. Approving replays the original request exactly as submitted. Poll GET /api/v1/agent/approvals/{id} until the status is completed, failed, rejected or expired.

Approval does not widen the request: the replay runs with your key's scopes and role cap, and the action is recorded as that key's, not the approver's. A queued request is also refused if its target is not in the key's workspace, so you will never be asked to approve a delete on someone else's resource.

Do not retry a pending_approval response — that queues a second request.

Idempotency

Send Idempotency-Key: <unique string> on any POST, PUT, PATCH or DELETE. A retry with the same key and body replays the original response instead of doing the work twice. Reusing a key with a different body returns 422.

This matters most for agents: a request that times out mid-deploy will be retried, and without an idempotency key that would create a second site.

Rate limits and spend caps

Each key has a requests-per-minute limit (default 120, configurable per key). Exceeding it returns 429 with details.retryAfterSeconds.

Each key can also carry a monthly spend cap. Exceeding it returns 403 SPEND_CAP_EXCEEDED with the cap, the amount already spent, and the currency.

Reference

  • api
  • rest
  • api key
  • authentication
  • openapi
  • swagger
  • idempotency

Ready to use this

Everything the API provisions is a catalog plan you can see priced first.

  • Same catalog the console reads
  • INR pricing, GST included
See the plans behind the API
Still stuck? Open a ticket from Support tickets in the console, or email [email protected]. Include the service name, the exact error and what you already tried.