The REST API in 5 minutes

APIImpreza documentationRead as Markdown ↗

Prefer to script it yourself? Every Impreza operation is a plain HTTP endpoint. This is the shortest path from curl to a live app: how to authenticate, what comes back, and the three calls that cover most of what you will do.

The basics

• Base URL: https://api.imprezahost.com
• Auth: two headers, X-API-Key: imp_… + X-API-Secret: …
• IP factor (per key, optional): each key has an IP mode — whitelist (default; add the caller's IP or get 403 IP_NOT_WHITELISTED), tofu (auto-pins the first IP), or keyonly (no IP factor — handy for CI). Keys can also be scoped (read/deploy/manage) and given an expiry.
• Rate limit: 60 req/min/key by default (raise per-key in the clientarea).
• Envelope: every response is {success, data, error, meta:{request_id, timestamp}}.

Direct Tor access: the REST API base URL is http://api.imprezareshna326gqgmbdzwmnad2wnjmeowh45bs2buxarh5qummjad.onion. Append the same /v1/... routes and use a Tor SOCKS proxy with remote hostname resolution (for curl, --proxy socks5h://127.0.0.1:9150 when Tor Browser listens on that port). Do not send credentials through a public onion gateway. Open the onion customer portal to manage your credentials. See all official Tor addresses and connection requirements.

Get your key first. Portal → Impreza API → Generate New Key (copy the secret, it shows once). Pick an IP mode — leave it on whitelist and add your IP under the IP Whitelist tab (curl https://api.ipify.org), or choose tofu / keyonly to skip that step. Full walk-through in Tutorial 1 → API key.

Step 0 — Confirm auth works

The cheapest call. If this returns your account, your key + IP are good:

curl https://api.imprezahost.com/v1/account \
  -H "X-API-Key: imp_..." -H "X-API-Secret: ..."

A 403 IP_NOT_WHITELISTED here means the key is in whitelist mode and this IP isn’t listed (add it, or switch the key to tofu/keyonly); a 401 means the key/secret is wrong.

Step 1 — Find your server (the agent_id)

Every deploy targets an agent. List your servers to get the agt_… id:

curl https://api.imprezahost.com/v1/platform/servers \
  -H "X-API-Key: imp_..." -H "X-API-Secret: ..."
# → data.servers[].agent_id   ("status": "online" is the one you want)

Empty list or "no servers on your account"? You have a VPS but no agent installed. See Tutorial 2 → the agent.

Step 2 — Deploy a catalog app

One POST. Leave domain out to auto-allocate a free *.imprezaapps.com subdomain:

curl -X POST https://api.imprezahost.com/v1/platform/deployments \
  -H "X-API-Key: imp_..." -H "X-API-Secret: ..." \
  -H "Content-Type: application/json" \
  -d '{
    "app_name": "vaultwarden",
    "agent_id": "agt_xxxxxxxxxxxx",
    "domain": "vault.example.com",
    "onion": true
  }'
# → data.deployment_id (dpl_…), data.url, data.onion_address

Step 3 — Deploy your own code

The same endpoint family, under /custom. Easiest source is a public git URL — the agent clones and builds it:

curl -X POST https://api.imprezahost.com/v1/platform/deployments/custom \
  -H "X-API-Key: imp_..." -H "X-API-Secret: ..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-app",
    "agent_id": "agt_xxxxxxxxxxxx",
    "git_url": "https://github.com/your-user/your-repo",
    "git_ref": "main",
    "dockerfile_path": "Dockerfile",
    "target_port": 8080,
    "cpus": 1.0,
    "memory_mb": 512
  }'

Other source modes: a public image, a local context_id (upload a gzip tarball to /v1/platform/deployments/custom/contexts first), or a full docker-compose manifest. Private git repos add git_auth_method (deploy_key or pat). The full request shapes are in Tutorial 2.

Managing what is running

Action	Endpoint
List deployments	GET /v1/platform/deployments
Show one	GET /v1/platform/deployments/{id}
Logs (tail N)	GET /v1/platform/deployments/{id}/logs
Restart	POST /v1/platform/deployments/{id}/restart
Change domain	POST /v1/platform/deployments/{id}/domain
Change settings (catalog)	GET/POST /v1/platform/deployments/{id}/vars
Add a .onion	POST /v1/platform/deployments/{id}/onion/add
Redeploy in place (custom)	POST /v1/platform/deployments/custom/{id}/redeploy
Uninstall	DELETE /v1/platform/deployments/{id}

Full reference

• Interactive Swagger UI over every endpoint: api.html
• Machine-readable spec: openapi.yaml (OpenAPI 3.1)
• Official SDKs wrap all of this — Go and Python. See Tutorial 4.

Not into raw HTTP? The impreza CLI packages and ships a project in one command, and an AI tool via MCP does it from chat — both ride this same API.