REST API

Base URL

Every endpoint lives under https://api.server4agent.com. Paths in the reference are written relative to it.

Authentication

Send your sk_live_ API key as a bearer token on every request. Keys are server-side secrets; never ship one in a browser bundle. Provisioning takes no body and no plan field; limits derive from the account behind the key.

curl -X POST https://api.server4agent.com/servers \
  -H "Authorization: Bearer $SERVER4AGENT_API_KEY"

# → { "id": "srv_2k9", "url": null, "status": "running", "tier": "small" }

Mint and scope keys from Authentication or the dashboard.

Errors

Every failure returns a JSON body { "error", "message" } with a machine-readable code:

• 400bad_request: The request was malformed.
• 401missing_or_invalid_api_key: Missing or invalid API key.
• 402budget_exceeded: Authorized, but the account is out of budget.
• 403plan_limit: A plan limit was hit (e.g. a tier's project cap).
• 404not_found: No such resource.
• 502compute_backend_error: The compute backend returned an error.

Projects & bring-up

POST /servers/{id}/projects accepts a source — blank, a template, a git repo, or an archive. For a source that carries code, the response includes an init_run_id and the project reports init_phase as it installs, starts, and healthchecks the app. Poll GET /projects/{id} or subscribe to the project.ready webhook. Full request and response schemas are in the reference above.

Secrets are environment variables bound server-wide or per project. Set them inline on create, or via PUT /secrets and PUT /projects/{id}/secrets; values are write-only and never returned. When bring-up finds env the code needs (from .env.example and process.env) that isn't set, it pauses at awaiting_secrets; supply the keys, or POST /projects/{id}/init with proceed to continue.