# Edit or archive a saved agent, writing a new revision.

`PATCH /o/{org}/agents/{agent}`

`If-Match` must carry the current revision (the `ETag` from a read). `{"archive": true}`
archives at the current revision and ignores every other field; there is no unarchive.
Otherwise omitted fields keep their current values, the merged config is re-validated
against today's catalog (or the `catalog_revision` sent), and a new revision is written,
even when only `name`/`description` changed. `handle` and `harness` are immutable.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org` | path | string | yes | The org's slug or id. A caller with no role in the org gets `404`. |
| `agent` | path | string | yes | The saved agent's id (UUID). Handles are not accepted here. |
| `If-Match` | header | string | yes | Current revision as an entity tag (`"3"`, `W/"3"` or bare `3`). |

## Request body

- `archive` (boolean, optional): `true` archives and ignores every other field.
- `name` (string, optional)
- `description` (string | null, optional): `null` clears it.
- `instructions` (string, optional)
- `catalog_revision` (string, optional): Defaults to the current catalog revision.
- `runtime` (object | object, optional)
- `defaults` (object, optional): Merged key by key over the current defaults.
  - `model` (SavedAgentModel, optional)
    - `selection` (string, required)
    - `id` (string, required): A model id the harness lists in `GET /o/{org}/agents/available`.
  - `effort` (string | null, optional)
  - `speed` (string, optional, one of `standard`, `fast`)
- `connection_refs` (array of SavedAgentConnectionRef, optional)
  - `kind` (string, required, one of `oauth`, `mcp`)
  - `id` (string, required)
- `capabilities` (object, optional): Merged key by key over the current capabilities.
  - `browser` (boolean, optional)
  - `computer` (boolean, optional)
- `tools` (object | object, optional)
- `network` (object | object, optional)
- `plugins` (array of object, optional)
  - `catalog_id` (string, required)

## Example request

```bash
curl -X PATCH "https://api.prix.dev/o/$RUSH_ORG/agents/$AGENT" \
  -H "Authorization: Bearer $RUSH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
```

```typescript
const org = process.env.RUSH_ORG;
const agent = process.env.AGENT;

const res = await fetch(`https://api.prix.dev/o/${org}/agents/${agent}`, {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.RUSH_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({}),
});

console.log(res.status, await res.json());
```

```python
import os

import requests

org = os.environ["RUSH_ORG"]
agent = os.environ["AGENT"]

res = requests.patch(
    f"https://api.prix.dev/o/{org}/agents/{agent}",
    headers={"Authorization": f"Bearer {os.environ['RUSH_TOKEN']}"},
    json={},
)

print(res.status_code, res.json())
```

## Responses

### 200

The agent at its new revision (or, for archive, at the unchanged revision with `archived: true`).

- `id` (string, required)
- `name` (string, required)
- `handle` (string, required)
- `description` (string, required)
- `harness` (string, required, one of `claude`, `codex`, `opencode`): Launch-boundary managed harnesses.
- `revision` (integer, required)
- `archived` (boolean, required)
- `source` (object | object | null, required)
- `config` (SavedAgentConfig, required): The desired configuration stored with one revision.
  - `harness` (string, required, one of `claude`, `codex`, `opencode`): Launch-boundary managed harnesses.
  - `catalog_revision` (string, required)
  - `runtime` (object | object, required)
  - `defaults` (object, required)
    - `model` (SavedAgentModel, required)
      - `selection` (string, required)
      - `id` (string, required): A model id the harness lists in `GET /o/{org}/agents/available`.
    - `effort` (string | null, required)
    - `speed` (string, required, one of `standard`, `fast`)
  - `instructions` (string, required)
  - `connection_refs` (array of SavedAgentConnectionRef, required)
    - `kind` (string, required, one of `oauth`, `mcp`)
    - `id` (string, required)
  - `capabilities` (object, required)
    - `browser` (boolean, required)
    - `computer` (boolean, required)
  - `tools` (object | object, required)
  - `network` (object | object, required)
  - `plugins` (array of object, required)
    - `catalog_id` (string, required)
- `resolved_at_save` (SavedAgentResolved, required): What the config resolved to against the catalog when this revision was saved.
  - `model` (string, required)
  - `effort` (string | null, required)
  - `speed` (string, required, one of `standard`, `fast`)
  - `harness_version` (string | null, required)
  - `tool_ids` (array of string | null, required)
  - `plugins` (array of object, required)
    - `catalog_id` (string, required)
    - `version` (string, required)
    - `digest` (string, required)
  - `runtime_id` (string | null, required)
  - `catalog_revision` (string, required)
  - `pin_guarantee` (boolean, required)
- `created_at` (string, required)
- `updated_at` (string, required)

### 401

No bearer, an unknown, revoked or expired one, or an API key on a route keys cannot call.

### 404

No such agent for the caller (`NOT_FOUND`).

### 412

`If-Match` is not the current revision, a concurrent write won, or the agent is already archived (`STALE_ETAG`).

### 422

Body refused: `IMMUTABLE_FIELD` (`handle` or `harness` sent), or any create-time
validation code (see `createSavedAgent`), including `CONNECTION_NOT_OWNED`.

### 428

`If-Match` missing or unparseable (`IF_MATCH_REQUIRED`).

## Example response (200)

```json
{
  "id": "3f6c1e2a-8b4d-4c1e-9a7f-2d5b6e8c0a14",
  "name": "string",
  "handle": "string",
  "description": "string",
  "harness": "claude",
  "revision": 1,
  "archived": true,
  "source": {
    "profile_id": "string",
    "revision": 1
  },
  "config": {
    "harness": "claude",
    "catalog_revision": "string",
    "runtime": {
      "selection": "latest_verified"
    },
    "defaults": {
      "model": {
        "selection": "pinned",
        "id": "string"
      },
      "effort": "none",
      "speed": "standard"
    },
    "instructions": "string",
    "connection_refs": [
      {
        "kind": "oauth",
        "id": "string"
      }
    ],
    "capabilities": {
      "browser": true,
      "computer": true
    },
    "tools": {
      "mode": "default"
    },
    "network": {
      "mode": "public"
    },
    "plugins": [
      {
        "catalog_id": "string"
      }
    ]
  },
  "resolved_at_save": {
    "model": "string",
    "effort": "none",
    "speed": "standard",
    "harness_version": "string",
    "tool_ids": [
      "string"
    ],
    "plugins": [
      {
        "catalog_id": "string",
        "version": "string",
        "digest": "string"
      }
    ],
    "runtime_id": "string",
    "catalog_revision": "string",
    "pin_guarantee": true
  },
  "created_at": "2026-10-06T12:00:00Z",
  "updated_at": "2026-10-06T12:00:00Z"
}
```