The REST API in 5 minutes

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}}.

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)

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 #

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.