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.

Moving a project to another Server4Agent deployment takes two calls. POST /projects/{id}/export packages the project into one file and returns a time-limited link to it; POST /servers/{id}/projects/import takes that file, base64 encoded, and recreates the project on the target. The bundle carries the source tree, the project's settings and its run plan. It leaves out dependency caches, git history and any .env or credential file, and it carries the names of the environment variables the project reads but never their values, so the import response lists what is still missing in missing_env. An imported project always lands private, on its own slug and URL.