---
title: "Replace an agent document"
description: "Whole-document replace. `If-Match` and the body's `updated_at` must both equal the agent's current `updated_at`; `id` and `slug`, when present, must match the URL."
url: https://docs.spinrun.ai/api/agents/replace-agent
markdown_url: https://docs.spinrun.ai/api/agents/replace-agent.md
---

# Replace an agent document

Whole-document replace. `If-Match` and the body's `updated_at` must both equal the agent's current `updated_at`; `id` and `slug`, when present, must match the URL.

## PUT /api/build/agents/{ref}

Replace an agent document

Whole-document replace. `If-Match` and the body's `updated_at` must both equal the agent's current `updated_at`; `id` and `slug`, when present, must match the URL.

Operation id: `replaceAgent`

### Parameters

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| ref | path | yes | string | Agent or workflow id or slug. |
| force | query | no | enum("true") | Set to `true` to drop webhook triggers the new document no longer names. |
| If-Match | header | yes | string | The document's current `updated_at` as an entity tag, e.g. `"2026-09-01T10:00:00.000Z"`, or `*`. |

### Request body

`application/json`

```json
{
  "type": "object",
  "properties": {
    "kind": {
      "type": "string",
      "const": "spinrun.agent/v1",
      "description": "Document discriminator."
    },
    "id": {
      "description": "Server id. Omit when creating.",
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "slug": {
      "description": "URL slug. Cannot change after creation.",
      "type": "string",
      "minLength": 1,
      "maxLength": 160
    },
    "status": {
      "description": "Read-only lifecycle status.",
      "type": "string",
      "enum": [
        "draft",
        "active",
        "archived"
      ]
    },
    "updated_at": {
      "description": "Version stamp. Required on replace; travels as If-Match too.",
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80,
      "description": "Display name."
    },
    "description": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 500
        },
        {
          "type": "null"
        }
      ],
      "description": "What the agent does."
    },
    "icon": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 40
        },
        {
          "type": "null"
        }
      ],
      "description": "Icon preset."
    },
    "space": {
      "type": "object",
      "properties": {
        "team": {
          "anyOf": [
            {
              "type": "string",
              "minLength": 1,
              "maxLength": 160,
              "description": "A human name for the thing: slug, address or id."
            },
            {
              "type": "null"
            }
          ],
          "description": "Team slug, or null for the workspace space."
        }
      },
      "required": [
        "team"
      ],
      "description": "Where the agent lives."
    },
    "folder": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 1000
        },
        {
          "type": "null"
        }
      ],
      "description": "Folder path within the space."
    },
    "instructions": {
      "type": "string",
      "maxLength": 8192,
      "description": "The system instructions."
    },
    "model": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120,
      "description": "Model id, e.g. spinrun default or a named model."
    },
    "max_steps": {
      "type": "integer",
      "minimum": 1,
      "maximum": 40,
      "description": "Maximum tool steps per run."
    },
    "reasoning_effort": {
      "description": "Absent = the model default.",
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "low",
            "medium",
            "high"
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "tools": {
      "type": "object",
      "properties": {
        "apps": {
          "maxItems": 50,
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160,
            "description": "A human name for the thing: slug, address or id."
          },
          "description": "App slugs the agent may use."
        },
        "connections": {
          "anyOf": [
            {
              "type": "string",
              "const": "all"
            },
            {
              "minItems": 1,
              "maxItems": 200,
              "type": "array",
              "items": {
                "type": "string",
                "minLength": 1,
                "maxLength": 160,
                "description": "A human name for the thing: slug, address or id."
              }
            }
          ],
          "description": "\"all\" or explicit connection addresses."
        },
        "disabled_tools": {
          "maxItems": 200,
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160,
            "description": "A human name for the thing: slug, address or id."
          },
          "description": "Tool slugs to hide."
        },
        "approval": {
          "type": "string",
          "enum": [
            "destructive",
            "write"
          ],
          "description": "Which tool calls need human approval."
        }
      },
      "required": [
        "apps",
        "connections",
        "disabled_tools",
        "approval"
      ],
      "description": "What the agent may touch."
    },
    "skills": {
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "string",
// … 345 more lines elided
```

### Responses

| Status | Description |
|---|---|
| 200 | Replaced. `ETag` carries the new `updated_at`. |
| 400 | Malformed JSON, a document that fails validation, or a field that contradicts the URL. |
| 401 | No or invalid token. The `WWW-Authenticate` header names the authorization server. |
| 403 | The grant has no Build authorization. |
| 404 | No such agent, workflow or run visible to this token. |
| 409 | The document changed since it was read (`current` and `applied` say where to rebase), or the write half-landed, or the document's state refuses the change. |
| 413 | Body over the document limit (64 KiB). |
| 428 | `If-Match` is required when replacing. |

#### 200 · `application/json`

```json
{
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "document": {},
        "applied": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "changes": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "version": {
          "type": "number"
        },
        "webhook_urls": {
          "description": "Present on agent writes that created a webhook trigger: the one-time URL, shown once.",
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "trigger_id": {
                "type": "string"
              },
              "url": {
                "type": "string"
              }
            },
            "required": [
              "trigger_id",
              "url"
            ],
            "additionalProperties": false
          }
        }
      },
      "required": [
        "document",
        "applied",
        "changes",
        "version"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "data"
  ],
  "additionalProperties": false
}
```

#### 400 · `application/json`

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}
```

#### 401 · `application/json`

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}
```

#### 403 · `application/json`

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}
```

#### 404 · `application/json`

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}
```

#### 409 · `application/json`

```json
{
  "anyOf": [
    {
      "type": "object",
      "properties": {
        "error": {
          "type": "string"
        },
        "current": {
          "description": "The current document, or null when nothing was read."
        },
        "applied": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Stages that had already landed before the refusal."
        }
      },
      "required": [
        "error",
        "current",
        "applied"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "error": {
          "type": "string"
        }
      },
      "required": [
        "error"
      ],
      "additionalProperties": false
    }
  ]
}
```

#### 413 · `application/json`

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}
```

#### 428 · `application/json`

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}
```