Aetherfy agent lifecycle API

Base URL https://agents.aetherfy.com/api/v1, bearer authentication, and the shared error envelope are described on the Agent REST API index. {agent} accepts a UUID or a name throughout.

Creating an Aetherfy agent

POST /api/v1/agents → 201

curl -s -X POST https://agents.aetherfy.com/api/v1/agents \
  -H "Authorization: Bearer $AETHERFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"reporter","runtime":"python3.12","memory_mb":512,"agent_type":"job"}'

Runtimes: python3.11, python3.12, python3.13, node20, node22, node20-ts, node22-ts, bun, dockerfile.

Creating an agent does not deploy it — it reserves the name and the configuration. See Deployments.

Your agent quota is not checked here. The quota counts deployed agents, and a freshly created agent is a draft, so you can keep as many drafts as you like on any plan — including building a replacement for an agent that is currently serving traffic, before you take the old one down. It is checked when you first deploy an agent, and when you restore one from the archive.

Which agents hold a slot follows from that. A deployed agent holds one, and stopping it does not give it back: a stopped agent is paused, which keeps it deployed. Archiving or deleting an agent releases its slot. Drafts never held one.

The per-agent caps are checked here — memory, idle timeout, always-on and the dockerfile runtime are all validated against your plan before the record is written, and an over-cap create is refused with PLAN_LIMIT_EXCEEDED.

Checking the quota at deploy rather than at create is not merely a deferral, and the deploy-time check is not redundant with anything: an agent created under your limit can reach its first deploy after a downgrade, or after another agent took the last slot.

Listing and reading Aetherfy agents

GET /api/v1/agents → 200, an array of agent objects. GET /api/v1/agents/{agent} → 200, one agent object.

curl -s https://agents.aetherfy.com/api/v1/agents/reporter \
  -H "Authorization: Bearer $AETHERFY_API_KEY"

The agent object carries the creation fields above plus:

failure_code is set only where the reason cannot be recovered from anything else. Today it carries one value, app_lost_on_provider: the compute plane no longer has an app for the agent. Your code, your secrets and the agent’s address are all kept, and afy deploy <agent> brings it back. A null failure_code is not a claim that the agent is healthy — an agent whose build did not compile has null here and explains itself through its deployment’s error instead.

failure_code is separate from is_degraded on purpose. is_degraded means the agent is serving and something about it is wrong; a failed agent is not serving at all, so the two never describe the same condition.

The cron_* fields describe a scheduled task. cron names the expression format only.

Aetherfy agent statuses

paused and stopped are different states with different causes, and the distinction matters when you are diagnosing an agent that is not serving. paused is something you did and can undo with start. stopped means the account was suspended — settle it and Aetherfy returns the agent to running on its own. See Billing and spend caps.

Updating an Aetherfy agent

PATCH /api/v1/agents/{agent} → 200. Every field is optional; omitted fields are untouched. Setting workspace_name to null moves the agent out of any workspace.

curl -s -X PATCH https://agents.aetherfy.com/api/v1/agents/reporter \
  -H "Authorization: Bearer $AETHERFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"memory_mb":1024,"keep_alive":true}'

Configuration changes here take effect on the next deploy. To change what is running now, deploy again.

Stopping and starting an Aetherfy agent

POST /api/v1/agents/{agent}/stop → 202 {"status": "paused", "machines": "stopping", "agent_id": "…"} POST /api/v1/agents/{agent}/start → 202 {"status": "running", "agent_id": "…"}

curl -s -X POST https://agents.aetherfy.com/api/v1/agents/reporter/stop \
  -H "Authorization: Bearer $AETHERFY_API_KEY"

Stop moves the agent to paused — note the endpoint is named for the verb and the resulting status is paused, not stopped. The agent keeps its slot against your plan’s agent count, its configuration and its code. Start brings the same machines back without rebuilding.

The pause is in force the moment the call returns: the status is paused, billing for machine uptime stops at that instant, and a deploy or rollback against the agent is already refused. The machines field reports the remaining work — the machines wind down in the background, and the machine states you see under GET /api/v1/agents/{agent}/status catch up afterwards rather than immediately.

Nothing you can do with the agent waits on that. start works straight away, even on machines still shown as stopping, and the pause is already reflected everywhere it matters. Treat the machine states as a view that trails, not as the pause itself.

Because a paused agent still holds its quota slot, you cannot pause your way under an agent limit. Archive instead.

AGENT_OPERATION_IN_PROGRESS is the only 409 here that is safe to retry blindly; the others describe a state you have to change first.

Archiving and restoring an Aetherfy agent

POST /api/v1/agents/{agent}/archive → 202 {"status": "archiving", …} POST /api/v1/agents/{agent}/restore → 202 {"status": "restoring", …}

Archiving tears the agent’s infrastructure down and releases its quota slot, keeping its configuration and stored code. It is the way to get under your agent limit without deleting anything.

Restoring rebuilds it — and re-checks quota at that moment, because other agents may have taken the slot meanwhile. An archived agent is therefore not guaranteed to come back if you have filled your plan since.

Deleting an Aetherfy agent

DELETE /api/v1/agents/{agent} → 202 {"status": "deleting", "agent_id": "…"}

Deletion is permanent and asynchronous: the agent moves to deleting and a worker tears down machines and stored code. It is refused while something still depends on the agent.

Deleting is not how you free a quota slot temporarily. Archive does that reversibly.

Reading live Aetherfy machine status

GET /api/v1/agents/{agent}/status → 200

curl -s https://agents.aetherfy.com/api/v1/agents/reporter/status \
  -H "Authorization: Bearer $AETHERFY_API_KEY"

{
  "agent_id": "6f1c2b7e-0a2d-4f8e-9c31-2b0d5a7e4411",
  "name": "reporter",
  "status": "running",
  "url": "https://reporter-k3m7x2.aetherfy.dev",
  "machines": [
    {
      "id": "1857a3d4f21e08",
      "region": "iad",
      "state": "started",
      "source": "live",
      "health": "passing",
      "last_check": "2026-08-19T09:12:44Z",
      "instance_id": "01J9…"
    }
  ]
}

This route differs from GET /agents/{agent} in one important way: it queries the machine host directly, so machines[].state is real-time rather than whatever Aetherfy last recorded.

Read source before trusting state. It is "live" when that machine was in the host’s response, and "cached" when Aetherfy fell back to its own last-known value because the host read failed. A cached reading can be up to about a minute stale. If your automation waits for a machine to reach a state, require source == "live" — otherwise a stale reading can satisfy the wait before the state is actually true.

url is null until the agent has machines. Destroyed machines are omitted.

Exporting an Aetherfy agent’s aetherfy.yaml

GET /api/v1/agents/{agent}/yaml → 200, Content-Type: application/yaml

curl -s https://agents.aetherfy.com/api/v1/agents/reporter/yaml \
  -H "Authorization: Bearer $AETHERFY_API_KEY" \
  -o aetherfy.yaml

The response body is YAML, not JSON. It is the declarative subset of the agent’s current configuration — the same content the dashboard’s download button produces — so it round-trips: write it into a project directory and deploy, and you get the agent back. See the aetherfy.yaml reference.

Returns 404 AGENT_NOT_FOUND for an agent being deleted.