# Update an org agent > The agents.update operation: PATCH /api/v1/agents/{id} in the REST API and the agents_update tool in the MCP server. Changes an agent's name, description, contact or vendor, its `role` and `scope`, live access (`livemodeAccess`), token `scopes`, `limits`, `toolSets` or whether every token must be DPoP-bound (`dpopBoundAccessTokens`: then the token endpoint refuses a request without a `DPoP` proof; tokens already issued keep working until they expire). Send only what changes; `null` in `limits` clears a value. Changes apply to the agent's next call: role, scope and live access are read on every call, and its current tokens are narrowed to the new scopes at once (wider scopes need a new token). The same rules as creating apply: never `org_owner`, never more than you have yourself at the agent's scope and mode. A revoked agent can't be changed. `limits` are enforced on every call (spec §41.4): `rps` operation calls per second (`agent_rate_limited`), `mutationsPerDay` changes per UTC day and mode (`agent_daily_limit_reached`), and `amountLimits` per financial operation and currency: a call above `perCall`, or above `perDay` with what the agent already moved today, or without an amount, **creates an approval request instead of running**. Amount limits apply only to operations that carry an amount (those an approval policy can limit). ## At a glance - **REST:** `PATCH /api/v1/agents/{id}` - **MCP tool:** `agents_update` - **Operation ID:** `agents.update` - **Scope:** Organization - **Permission:** `agents:admin` - **Risk tier:** `security` - **Dry run:** Supported (send `Ownrecord-Dry-Run: true`) - **Idempotency:** `Idempotency-Key` optional - **Modes:** Test and live - **Authentication:** API key with the `agents:admin` scope - **Since:** M10 ## Request ### Path parameters | Field | Type | Description | | ----- | ---------- | ----------- | | `id` | `agt_…` ID | | ### Body A JSON object (`Content-Type: application/json`): | Field | Type | Required | Description | | ----------------------------------- | -------------------------------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------- | | `name` | string | No | | | `description` | string or null | No | | | `contact` | string or null | No | | | `vendor` | string or null | No | | | `role` | one of `org_admin`, `billing_admin`, `finance`, `tax_manager`, `support`, `developer`, `viewer` | No | | | `scope` | object | No | | | `livemodeAccess` | boolean | No | | | `scopes` | array of one of 84 values, e.g. `org:read`, `org:write`, `org:admin` (all in the OpenAPI document) | No | | | `dpopBoundAccessTokens` | boolean | No | Require DPoP for every token: a token request without a DPoP proof is refused (RFC 9449). | | `limits` | object | No | | | `limits.rps` | integer (1 to 10000) or null | No | | | `limits.mutationsPerDay` | integer (0 to 10000000) or null | No | | | `limits.amountLimits` | array of object | No | | | `limits.amountLimits[].operationId` | string | Yes | | | `limits.amountLimits[].perCall` | money or null | No | | | `limits.amountLimits[].perDay` | money or null | No | | | `toolSets` | array of string | No | | ## Response `200 OK` with a JSON object: | Field | Type | Description | | ----------------------------------- | -------------------------------------------------------------------------------------------------- | ----------- | | `id` | `agt_…` ID | | | `object` | `"agent"` | | | `orgId` | `org_…` ID | | | `name` | string | | | `description` | string or null | | | `contact` | string or null | | | `vendor` | string or null | | | `ownerType` | one of `org`, `app` | | | `appInstallationId` | `ains_…` ID or null | | | `role` | one of `org_admin`, `billing_admin`, `finance`, `tax_manager`, `support`, `developer`, `viewer` | | | `scope` | object | | | `livemodeAccess` | boolean | | | `limits` | object | | | `limits.rps` | integer or null | | | `limits.mutationsPerDay` | integer or null | | | `limits.amountLimits` | array of object | | | `limits.amountLimits[].operationId` | string | | | `limits.amountLimits[].perCall` | money or null | | | `limits.amountLimits[].perDay` | money or null | | | `toolSets` | array of string | | | `status` | one of `active`, `paused`, `revoked` | | | `clientId` | `ocl_…` ID | | | `authMethod` | one of `client_secret_basic`, `client_secret_post`, `private_key_jwt` | | | `secretPrefix` | string or null | | | `dpopBoundAccessTokens` | boolean | | | `scopes` | array of one of 84 values, e.g. `org:read`, `org:write`, `org:admin` (all in the OpenAPI document) | | | `createdBy` | string | | | `createdAt` | string | | | `updatedAt` | string | | | `pausedAt` | string or null | | | `revokedAt` | string or null | | ## Examples ### Enable live mode ```http PATCH /api/v1/agents/agt_01m4ttwd3veh9apbewxheq5xh8 Authorization: Bearer or_test_… Content-Type: application/json { "livemodeAccess": true } ``` Response (`200`): ```json { "id": "agt_01m4ttwd3veh9apbewxheq5xh8", "object": "agent", "orgId": "org_01m4ttwd3veh9apbewxheq5xh3", "name": "Bookkeeper", "description": "Prepares and files the quarterly OSS return", "contact": "ops@acme.example", "vendor": "In-house, Claude via the MCP server", "ownerType": "org", "appInstallationId": null, "role": "finance", "scope": { "type": "org" }, "livemodeAccess": true, "limits": { "rps": null, "mutationsPerDay": null, "amountLimits": [ { "operationId": "refunds.create", "perCall": null, "perDay": { "amount": "200000000", "currency": "EUR" } } ] }, "toolSets": [], "status": "active", "clientId": "ocl_01m4ttwd3veh9apbewxheq5xh9", "authMethod": "client_secret_basic", "secretPrefix": "or_cs_Exampl", "dpopBoundAccessTokens": false, "scopes": ["filings:read", "filings:write", "tasks:read", "tasks:write"], "createdBy": "usr_01m4ttwd3veh9apbewxheq5xh6", "createdAt": "2026-10-25T09:00:00.000Z", "updatedAt": "2026-10-26T14:30:00.000Z", "pausedAt": null, "revokedAt": null } ``` ### Refunds up to €50 each and €200 a day; above, a person approves ```http PATCH /api/v1/agents/agt_01m4ttwd3veh9apbewxheq5xh8 Authorization: Bearer or_test_… Content-Type: application/json { "limits": { "amountLimits": [ { "operationId": "refunds.create", "perCall": { "amount": "50000000", "currency": "EUR" }, "perDay": { "amount": "200000000", "currency": "EUR" } } ] } } ``` Response (`200`): ```json { "id": "agt_01m4ttwd3veh9apbewxheq5xh8", "object": "agent", "orgId": "org_01m4ttwd3veh9apbewxheq5xh3", "name": "Bookkeeper", "description": "Prepares and files the quarterly OSS return", "contact": "ops@acme.example", "vendor": "In-house, Claude via the MCP server", "ownerType": "org", "appInstallationId": null, "role": "finance", "scope": { "type": "org" }, "livemodeAccess": false, "limits": { "rps": null, "mutationsPerDay": null, "amountLimits": [ { "operationId": "refunds.create", "perCall": { "amount": "50000000", "currency": "EUR" }, "perDay": { "amount": "200000000", "currency": "EUR" } } ] }, "toolSets": [], "status": "active", "clientId": "ocl_01m4ttwd3veh9apbewxheq5xh9", "authMethod": "client_secret_basic", "secretPrefix": "or_cs_Exampl", "dpopBoundAccessTokens": false, "scopes": ["filings:read", "filings:write", "tasks:read", "tasks:write"], "createdBy": "usr_01m4ttwd3veh9apbewxheq5xh6", "createdAt": "2026-10-25T09:00:00.000Z", "updatedAt": "2026-10-26T14:30:00.000Z", "pausedAt": null, "revokedAt": null } ``` ### Require DPoP-bound tokens From now on the token endpoint refuses the agent's token requests without a DPoP proof. ```http PATCH /api/v1/agents/agt_01m4ttwd3veh9apbewxheq5xh8 Authorization: Bearer or_test_… Content-Type: application/json { "dpopBoundAccessTokens": true } ``` Response (`200`): ```json { "id": "agt_01m4ttwd3veh9apbewxheq5xh8", "object": "agent", "orgId": "org_01m4ttwd3veh9apbewxheq5xh3", "name": "Bookkeeper", "description": "Prepares and files the quarterly OSS return", "contact": "ops@acme.example", "vendor": "In-house, Claude via the MCP server", "ownerType": "org", "appInstallationId": null, "role": "finance", "scope": { "type": "org" }, "livemodeAccess": false, "limits": { "rps": null, "mutationsPerDay": null, "amountLimits": [ { "operationId": "refunds.create", "perCall": null, "perDay": { "amount": "200000000", "currency": "EUR" } } ] }, "toolSets": [], "status": "active", "clientId": "ocl_01m4ttwd3veh9apbewxheq5xh9", "authMethod": "client_secret_basic", "secretPrefix": "or_cs_Exampl", "dpopBoundAccessTokens": true, "scopes": ["filings:read", "filings:write", "tasks:read", "tasks:write"], "createdBy": "usr_01m4ttwd3veh9apbewxheq5xh6", "createdAt": "2026-10-25T09:00:00.000Z", "updatedAt": "2026-10-26T14:30:00.000Z", "pausedAt": null, "revokedAt": null } ``` ### Cap requests and mutations ```http PATCH /api/v1/agents/agt_01m4ttwd3veh9apbewxheq5xh8 Authorization: Bearer or_test_… Content-Type: application/json { "limits": { "rps": 5, "mutationsPerDay": 500 } } ``` Response (`200`): ```json { "id": "agt_01m4ttwd3veh9apbewxheq5xh8", "object": "agent", "orgId": "org_01m4ttwd3veh9apbewxheq5xh3", "name": "Bookkeeper", "description": "Prepares and files the quarterly OSS return", "contact": "ops@acme.example", "vendor": "In-house, Claude via the MCP server", "ownerType": "org", "appInstallationId": null, "role": "finance", "scope": { "type": "org" }, "livemodeAccess": false, "limits": { "rps": 5, "mutationsPerDay": 500, "amountLimits": [ { "operationId": "refunds.create", "perCall": null, "perDay": { "amount": "200000000", "currency": "EUR" } } ] }, "toolSets": [], "status": "active", "clientId": "ocl_01m4ttwd3veh9apbewxheq5xh9", "authMethod": "client_secret_basic", "secretPrefix": "or_cs_Exampl", "dpopBoundAccessTokens": false, "scopes": ["filings:read", "filings:write", "tasks:read", "tasks:write"], "createdBy": "usr_01m4ttwd3veh9apbewxheq5xh6", "createdAt": "2026-10-25T09:00:00.000Z", "updatedAt": "2026-10-26T14:30:00.000Z", "pausedAt": null, "revokedAt": null } ``` ## Errors | Code | HTTP status | When | What to do | | ------------------------------------------------------------------------------------------------------------ | ----------- | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed) | 400 | A field is invalid, e.g. a scope the role can't use, or an amount limit on an operation that moves no amount. | Fix the fields listed in `details.issues` and send the request again. | | [`agent_role_invalid`](https://ownrecord.io/docs/reference/errors.md#agent_role_invalid) | 400 | The role is org_owner, or isn't allowed at the scope's type. | Choose a role other than org_owner, at a scope the role allows (org, entity or brand; see the role table in the docs). | | [`agent_delegation_not_allowed`](https://ownrecord.io/docs/reference/errors.md#agent_delegation_not_allowed) | 403 | The agent would get a permission (or live access) you don't have at its scope. | Choose a narrower role, scope or token scopes, turn off live mode for the agent, or ask an organization owner to do it. | | [`agent_revoked`](https://ownrecord.io/docs/reference/errors.md#agent_revoked) | 409 | The agent is revoked. | Create a new agent instead. | | [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found) | 404 | No such agent, or the scope's entity or brand doesn't exist. | Check the ID and that your credentials are scoped to the right organization, entity, brand and mode. | | [`version_conflict`](https://ownrecord.io/docs/reference/errors.md#version_conflict) | 409 | The agent changed at the same moment; retry. | Fetch the object again and retry the change. | | [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied) | 403 | You can't manage agents. | Ask an organization owner or admin for a role or scope that allows this action. | It can also return these [common errors](https://ownrecord.io/docs/reference.md#common-errors): [`api_version_unsupported`](https://ownrecord.io/docs/reference/errors.md#api_version_unsupported), [`invalid_json`](https://ownrecord.io/docs/reference/errors.md#invalid_json), [`unsupported_media_type`](https://ownrecord.io/docs/reference/errors.md#unsupported_media_type), [`authentication_required`](https://ownrecord.io/docs/reference/errors.md#authentication_required), [`api_key_invalid`](https://ownrecord.io/docs/reference/errors.md#api_key_invalid), [`idempotency_key_reused`](https://ownrecord.io/docs/reference/errors.md#idempotency_key_reused), [`idempotency_in_progress`](https://ownrecord.io/docs/reference/errors.md#idempotency_in_progress), [`approval_required`](https://ownrecord.io/docs/reference/errors.md#approval_required), [`approval_rejected`](https://ownrecord.io/docs/reference/errors.md#approval_rejected), [`approval_expired`](https://ownrecord.io/docs/reference/errors.md#approval_expired), [`stale_approval`](https://ownrecord.io/docs/reference/errors.md#stale_approval), [`approval_policy_denied`](https://ownrecord.io/docs/reference/errors.md#approval_policy_denied), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).