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","description":"Posts the daily summary","workspace_name":"default"}'

Send workspace_name or workspace_id, exactly one: every agent lives in a workspace. Neither, or both, is 422 VALIDATION_ERROR. On an account with one workspace, that is default.

These are the platform’s fields, and the only ones a create takes. How the agent runs (its runtime, type, memory, always-on, idle timeout, regions, entrypoint, schedule and spawn) is set by its aetherfy.yaml at deploy; a create naming any of them is refused with 422 VALIDATION_ERROR.

Creating an agent does not deploy it — it reserves the name, in its workspace. 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 — memory, idle timeout, always-on, the dockerfile runtime — are checked at deploy, against the aetherfy.yaml being deployed.

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, and it can be set on any status. Today it carries 13 values, app_lost_on_provider, image_lost_on_provider, agent_unhealthy, machine_lost_on_provider, restore_refused_agent_limit, restore_refused_agent_safety_limit, restore_refused_usage_limit, restore_refused_payment_issue, restore_refused_code_unavailable, restore_refused_config_not_on_record, restore_refused_plan_settings, restore_refused_region_placement and restore_refused_other.

The first two sit on a failed agent. app_lost_on_provider means the compute plane no longer has an app for the agent. image_lost_on_provider means the image a service agent runs is no longer available, so nothing can start from it; a job agent is never marked this way, because its next run rebuilds the image instead. In both cases your secrets and the agent’s address are kept, and afy deploy, run in the agent’s project folder, brings it back from your current code.

Two sit on a running agent that is not serving. agent_unhealthy is set when every running machine of the agent is failing its health check, so none of them is being sent requests; a request may wake a resting machine, which then fails the same way if the code cannot start (see the machine health field below). failure_message then carries the error the machine reports, and the code clears by itself as soon as a machine passes again. If your code cannot start, fix it and run afy deploy in the agent’s folder. machine_lost_on_provider is set on a running service agent when the compute plane no longer runs any machine of its live release: the machine was lost, or the host it ran on is down. Nothing brings a machine back by itself, so the agent serves nothing until afy deploy (run in the agent’s folder) builds new machines; your secrets and the agent’s address are kept. It clears when a deploy goes live, or by itself if the host comes back and the machine runs again.

The seven restore_refused_* values sit on an archived agent: a restore was accepted with a 202 and then refused when it ran (see archiving and restoring). The agent stays archived, with its code, secrets and settings kept. Each value names one thing to do:

A restore refusal clears as soon as you ask for a restore again, and whenever the agent leaves archived by a restore, a deploy or a push. 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. For the same reason is_degraded is withheld, and degraded_reason is null, while agent_unhealthy explains the agent: an agent none of whose running machines is being sent requests is not serving, and its failure_message already carries the error the machine reports.

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

When an Aetherfy agent has a URL

url is the address you send requests to. It is null unless all three of these are true:

deployed and url answer different questions, and a type: job agent is where the difference shows: it deploys, so deployed is true, and it serves nothing, so url is null. Do not read url != null as “is it deployed” — read deployed.

An agent’s hostname is fixed for its lifetime. Renaming the agent does not move it, and neither does redeploying it or archiving and restoring it — so an integration pointing at the address never has to be updated. Archiving does take the agent off that address until you restore it, which is the first row above; what the fixed hostname guarantees is that it comes back on the same one.

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. It changes the platform’s two fields of an agent, name and description, and nothing else; each is optional, and an omitted one is untouched. description: null clears it. How the agent runs (memory, always-on, regions, schedule, and the rest) is set by its aetherfy.yaml and changes only by a deploy; a body naming any other field is refused with 422. Moving an agent to another workspace is POST /api/v1/agents/{agent}/move, which redeploys it there.

curl -s -X PATCH https://agents.aetherfy.com/api/v1/agents/reporter \
  -H "Authorization: Bearer $AETHERFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"daily-reporter","description":"Posts the daily summary"}'

A rename does not move the agent’s public URL.

Moving an Aetherfy agent to another workspace

POST /api/v1/agents/{agent}/move → 200. Send the target as workspace_name or workspace_id, exactly one.

curl -s -X POST https://agents.aetherfy.com/api/v1/agents/reporter/move \
  -H "Authorization: Bearer $AETHERFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"workspace_name":"research"}'

The running machines carry their workspace in their environment, so moving a live agent redeploys its serving release into the new workspace — its existing image, with no build — and the response carries that deployment. An agent with nothing serving moves without one. A move that cannot redeploy is refused, and the agent stays where it was. A grant the agent had to the target workspace is dropped, since that is now its own; the workspace it left does not become a grant.

The agent’s conversation history stays in the workspace it left. The memory SDK keeps conversations in each workspace’s __threads__ collection, shared by every agent living there, and that collection never moves; after the move the agent’s MemoryClient reads its new workspace’s. Its AETHERFY_WORKSPACE_ID is the new workspace’s from the redeploy on. A frozen account can never move an agent: a move grows nothing but reduces nothing either.

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": "…", "readiness": "serving", "resume": null}

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 — booted afresh, so your code starts from the top and nothing it held in memory survives the stop.

The pause is in force the moment the call returns: the status is paused, the agent’s awake time stops counting at that instant, and a deploy or rollback against the agent is already refused. A paused agent is still deployed, so it keeps accruing its daily price for its memory and regions; archive it to stop that (Billing). The machines field reports the remaining work — Aetherfy stops the machines in the background, giving your server its shutdown grace, and the machine states you see under GET /api/v1/agents/{agent}/status catch up afterwards rather than immediately.

A start sent before the machines are down is accepted, and carried out once they are — see below. Everything else already sees the agent paused. Treat the machine states as a view that trails, not as the pause itself.

For a service agent, start answers once every machine has booted and its own /health has answered, or 25 seconds have passed since the call arrived. readiness says which. A job agent is resumed without starting any machine: its machines serve only runs, so start restores its auto-start and answers running at once, and a machine wakes when a run needs it.

The wait costs a resume as long as your server takes to start, up to that bound. The agent is running either way: readiness describes your code, not the start.

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; the others describe a state you have to change first.

Starting while the previous stop is still finishing

stop answers once the pause is decided, and the stop itself runs after it, giving your server its shutdown grace — so a start sent right after a stop finds the stop still being carried out. That start is accepted:

POST /api/v1/agents/{agent}/start → 202 {"status": "paused", "agent_id": "…", "readiness": null, "resume": {"state": "pending", "reason": null, "requested_at": "…"}, "stop_bound_seconds": …, "wait_bound_seconds": …}

Nothing is started yet, and nothing needs retrying. Aetherfy keeps the request and starts the agent as soon as the stop completes — closing the dashboard or the terminal loses nothing. Every other start answer carries "resume": null.

• stop_bound_seconds is the longest the stop can still take: how long Aetherfy takes to pick it up, the stop itself and, when a stop attempt failed and is waiting to be retried, that wait too. It is 0 once the stop is done and only the start is left (resume.state is then queued).
• wait_bound_seconds is how long to wait for the outcome: stop_bound_seconds plus 159 seconds, Aetherfy’s pickup of the start and one full attempt at it. A start that works takes seconds.

If wait_bound_seconds passes with the agent still paused and resume still pending or queued, the start has not failed: its compute provider refused or was slow, and Aetherfy keeps retrying it on its own schedule. Stop waiting and read the agent later — resume becomes null with the agent running once it starts, or dropped, reason start_failed, if every retry fails. afy start --wait exits 4 at that point, and the dashboard says Aetherfy is still retrying.

Follow the agent on GET /api/v1/agents/{agent}. Its resume field says what became of the start:

Once the agent is started, it reads running and resume is null. afy start --wait follows this for you, and the dashboard shows the agent as starting once its stop finishes — or why the start was dropped. Sending start again while one is pending changes nothing.

resume.reason, when the start was dropped:

A dropped start stays on the agent until the agent next runs, or is paused again.

Starting when a machine’s host is full

A stopped machine resumes on the host it last ran on. When that host has no room left to resume it, start is accepted the same way, at once, instead of waiting while Aetherfy finds the machine a new host:

POST /api/v1/agents/{agent}/start → 202 {"status": "paused", "agent_id": "…", "readiness": null, "resume": {"state": "queued", "reason": null, "requested_at": "…", "cause": "host_full"}, "stop_bound_seconds": 0, "wait_bound_seconds": 413}

Aetherfy retries for about 30 seconds, then starts a new machine from the agent’s current release on a host that has room, and destroys the old machine once the new one is running. That is a cold start on a new machine, not a resume of the old one. wait_bound_seconds is 413 seconds: the pickup of the start, one attempt at it, the retries, and one new machine, which can take up to 224 seconds more for each further machine whose host was full.

resume.cause is null for a start accepted while the previous stop finishes.

Follow the agent as above. Once it reads running, its machines_recreated says how many of its machines were replaced this way — 0 when the retry got through and the old machine resumed where it was — and keeps saying so until the agent is paused again. afy start --wait names it as a cold start. If a new machine cannot be started either, Aetherfy retries the whole start on its own schedule, keeps the agent paused with its old machine, and resume ends dropped with reason start_failed if every retry fails.

The latest request wins:

• A stop while a start is pending cancels it and answers 202 as a pause (machines is stopped if the stop had already finished). The pause is your own latest request, so resume then reads null, not dropped. If the start is already being carried out, the stop answers AGENT_OPERATION_IN_PROGRESS; retry it once the agent is running.
• An archive or a delete cancels it (archived, deleted).
• If the stop fails for good, the start is not carried out: Aetherfy does not start machines whose state it could not establish. The agent stays paused and the start reads dropped, stop_failed. Start it again when you want it running.

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.

The 202 means the restore was accepted, not that it is done. When it runs it is checked again — the agent limit, the usage limit and payment, the stored code, the plan and the regions — and a restore refused then leaves the agent archived with failure_code naming the reason and the fix (see the values above). A restore that is still running has a null failure_code.

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",
      "run_id": null,
      "state": "started",
      "source": "live",
      "health": "ok",
      "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.

health is the last health-check reading of a started machine: ok, degraded or unhealthy. A machine in any other state reports unknown — health checks run only while a machine is started, so a task machine suspended between runs, or an idle service asleep, has no reading. That is a resting machine, not a problem.

A service machine whose health check fails is taken out of rotation: requests go only to the agent’s machines whose /health answers. If every machine of the agent fails its check, none of them is sent a request, so a request waits and is then answered 503. The wait is the compute plane’s own routing behaviour, not a platform setting: we measured 37 to 51 seconds. The agent’s reason says why, with the error its machine reports, and clears once a machine passes again. A second region gives the agent a second machine, which keeps serving while the other fails.

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

run_id names the run a machine is executing right now, and is null for a machine that is not executing one: a service’s machine, or a task machine resting between runs. It is how to tell which machine holds a run when a task agent has several.

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: the configuration the agent’s live release was deployed with, as recorded at that deploy. It has every field aetherfy.yaml owns, starts with the editor line # yaml-language-server: $schema=https://docs.aetherfy.com/aetherfy-yaml.schema.json, and never carries name, description or workspace. Deploying it unchanged releases the same configuration again. It is what the dashboard’s Download YAML, afy init --agent and afy diff read. See the aetherfy.yaml reference.

The live release is the newest active one (a paused or stopped agent keeps it); for an archived agent it is the newest archived one, which is what a restore releases.