Skip to main content

Documentation Index

Fetch the complete documentation index at: https://agent37.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

An instance is a persistent, isolated, always-on computer running your agent. Create one per end user. The call is synchronous: when status is running, it can take a message immediately. Creating an instance pre-charges prorated compute from your prepaid balance, but the agent does no work until you send it a message.

​
Create an instance

POST /v1/instances returns an instance that is ready to take a message the moment its status is running. Every field is optional, so a POST with no body works.
​
template
string
Which agents are installed. hermes is the default and available today; claude-code, codex, openclaw, and all are coming soon. See Templates.
​
vcpu
integer
default:"1"
Size: 1, 2, 4, or 8. Sets CPU, memory, disk, and price.
​
user
string
An opaque tag for your own attribution (your end user’s id). Stored, never interpreted. Filter the list by it.
​
managed_credit_cap_usd
number
default:"1.00"
Hard cap on this instance’s managed usage, drawn from your shared balance.
​
name
string
A label for the instance.
​
metadata
object
Your own key/value pairs. Stored, never interpreted.
Today every instance runs the hermes template. The claude-code, codex, openclaw, and all templates, plus bring-your-own custom templates, are coming soon. See Templates.

​
Create body and instance object

curl -X POST https://api.agent37.com/v1/instances \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "template": "hermes", "vcpu": 2, "user": "u_882" }'
​
id
string
The instance id, prefixed inst_.
​
status
string
running means it can take a message now.
​
template
string
The template the instance was built from.
​
agents
string[]
The agents the template installed (Hermes by default).
​
vcpu
integer
The current size.
​
user
string
Your attribution tag, echoed back.
​
balance
object
Per-instance managed-usage tracking: managed_cap_usd, managed_used_usd, and remaining_usd.
​
update_available
boolean
true when a newer template version exists. Apply it with the /update endpoint.
​
created
integer
Creation time in unix seconds.

​
Manage it

ActionEndpoint
Retrieve / listGET /v1/instances/{id} · GET /v1/instances?user=
Update (name, cap, resize vcpu)PATCH /v1/instances/{id}
Delete / restoreDELETE /v1/instances/{id} · POST /v1/instances/{id}/restore
Delete frees the seat. An instance occupies one of your pre-purchased seats for as long as it exists, running or idle, since it runs continuously (cron, heartbeats). Delete archives it and opens the seat so a new instance can take its spot. There is no refund; the seat is already yours to reuse. The data stays recoverable with restore. Add ?permanent=true to purge it.

​
Lifecycle

Three calls control whether the instance’s computer is running and which version it runs. Each is a POST to a subpath, takes no body, and returns the instance with its new status. Everything on the instance (files, memory, connected accounts) survives all three.

​
Stop

POST /v1/instances/{id}/stop halts the container. The agent stops doing work (no cron, no heartbeats, no responses) and status becomes stopped. The instance and its data stay intact; bring it back up with restart.
curl
curl -X POST https://api.agent37.com/v1/instances/inst_x7/stop \
  -H "Authorization: Bearer sk_live_..."
# -> { "id": "inst_x7", "status": "stopped", ... }
Stopping does not free the seat. A stopped instance still occupies its pre-purchased seat, just like a running one. To open the seat for another instance, delete it (see above).

​
Restart

POST /v1/instances/{id}/restart recreates the container from the image already on the host (no download), then returns it to running. Use it to recover a wedged agent, to pick up changed settings, or to bring a stopped instance back up. Same template version, same data.
curl
curl -X POST https://api.agent37.com/v1/instances/inst_x7/restart \
  -H "Authorization: Bearer sk_live_..."
# -> { "id": "inst_x7", "status": "running", ... }

​
Update

POST /v1/instances/{id}/update pulls the latest version of the instance’s template, recreates the container on it, and preserves the data. The instance object’s update_available is true whenever a newer version exists, and this call is how you apply it.
curl
curl -X POST https://api.agent37.com/v1/instances/inst_x7/update \
  -H "Authorization: Bearer sk_live_..."
# -> { "id": "inst_x7", "status": "running", "update_available": false, ... }

​
Next steps

Templates

Choose which agents an instance installs.

Billing

Prepaid balance, managed caps, and pricing.