# Worker deployment HTTP API

Create, read, replace and remove durable builtin worker deployments.

A worker deployment stores how a builtin worker should run. Its desired state is durable. The managed-worker read joins that record with the process currently supervised on this node.

## Routes and fields

- `GET /worker-deployments`: List durable deployment records and undecodable rows separately. Requires enabled deployment and the deploy grant.
- `GET /worker-deployments/{name}`: Read one durable worker record; absent names return not-found.
- `PUT /worker-deployments/{name}`: Create or replace. Required body fields: artifact, namespaces, task_queue, desired. Optional node. Returns outcome and deployment. The node acts on the new desired state before answering.
- `POST /worker-deployments/{name}/desired-state`: Body: {"desired":"running"} or {"desired":"stopped"}. Persists desired state and asks this node’s supervisor to apply it.
- `DELETE /worker-deployments/{name}`: Delete the record and ask supervision to stop and forget the process. Returns existed plus the removed deployment; a missing name returns not-found. Read logs if stopping fails.
- `Artifact`: Only type builtin is accepted. verb is the argument list after this server’s executable path. The server captures its binary identity. Names beginning auto/ are reserved.


## Put a record

Save this worker document at the named path on the server host. Replace that path and the gRPC endpoint in the deployment request for your installation. The queue and launch arguments must agree with the document.

**/srv/aion/reviewers.awl — on the server host**

```text
//! Serve a prompt by returning its text.
worker reviewers
  action review(prompt: String) -> String
    run text "printf %s {{prompt}}"
```


Start with desired stopped so you can inspect the record before launching it.

**Terminal — create a stopped builtin AWL worker**

```bash
curl --fail-with-body -sS -X PUT "${AION_HTTP_ENDPOINT:-http://127.0.0.1:8080}/worker-deployments/reviewers" \
  -H "authorization: Bearer $AION_TOKEN" \
  -H 'content-type: application/json' \
  --data-binary '{"artifact":{"type":"builtin","verb":["worker","awl","/srv/aion/reviewers.awl","--endpoint","http://127.0.0.1:50051","--namespace","default","--concurrency","2","--reconnect-initial-backoff","0.1","--reconnect-max-backoff","5","--reconnect-max-attempts","100"]},"namespaces":["default"],"task_queue":"reviewers","node":null,"desired":"stopped"}'
```


The builtin artifact launches the server executable with the declared worker command. The supervisor supplies its deployment identity. This request includes concurrency and reconnect settings; add the worker authentication settings required by your server.

## Read and start

**Terminal — read desired and actual state**

```bash
curl --fail-with-body -sS -X GET "${AION_HTTP_ENDPOINT:-http://127.0.0.1:8080}/worker-deployments/reviewers" \
  -H "authorization: Bearer $AION_TOKEN"
curl --fail-with-body -sS -X GET "${AION_HTTP_ENDPOINT:-http://127.0.0.1:8080}/workers/managed" \
  -H "authorization: Bearer $AION_TOKEN"
```


After reviewing the launch and [supervision policy](/aion/reference/configuration-workers/), request running state.

**Terminal — request running state**

```bash
curl --fail-with-body -sS -X POST "${AION_HTTP_ENDPOINT:-http://127.0.0.1:8080}/worker-deployments/reviewers/desired-state" \
  -H "authorization: Bearer $AION_TOKEN" \
  -H 'content-type: application/json' \
  --data-binary '{"desired":"running"}'
```


Replacement updates the stored launch and replaces a supervised instance using the old launch. Read the managed status and logs to confirm the new process registered successfully.

The implementation is in the HTTP router’s worker deployment family and the worker deployment handlers. Deletion logs a stopping failure even after deleting its record; retain the process identity before deleting a running deployment.