Update an org agent · Ownrecord docs

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`	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`	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`	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`	409	The agent is revoked.	Create a new agent instead.
`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`	409	The agent changed at the same moment; retry.	Fetch the object again and retry the change.
`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: api_version_unsupported, invalid_json, unsupported_media_type, authentication_required, api_key_invalid, idempotency_key_reused, idempotency_in_progress, approval_required, approval_rejected, approval_expired, stale_approval, approval_policy_denied, rate_limited, internal_error.

At a glance#

Request#

Path parameters#

Body#

Response#

Examples#

Enable live mode#

Refunds up to €50 each and €200 a day; above, a person approves#

Require DPoP-bound tokens#

Cap requests and mutations#

Errors#

At a glance

Request

Path parameters

Body

Response

Examples

Enable live mode

Refunds up to €50 each and €200 a day; above, a person approves

Require DPoP-bound tokens

Cap requests and mutations

Errors