Pause an org agent · Ownrecord docs

Pauses an agent: every access token it holds is revoked at once, and it can't get new ones until it is resumed (agents.resume). Its credentials stay valid for after the resume. Pausing a paused agent changes nothing; a revoked agent can't be paused.

At a glance

REST: POST /api/v1/agents/{id}/pause
MCP tool: agents_pause
Operation ID: agents.pause
Scope: Organization
Permission: agents:admin
Risk tier: security
Dry run: Supported (send Ownrecord-Dry-Run: true)
Idempotency: Idempotency-Key required
Modes: Test and live
Authentication: API key with the agents:admin scope
Since: M10

Request

Path parameters

Field	Type	Description
`id`	`agt_…` ID

Body

This operation takes no body.

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

Pause an agent

HTTP

POST /api/v1/agents/agt_01m4ttwd3veh9apbewxheq5xh8/pause
Authorization: Bearer or_test_…
Idempotency-Key: 3f1c9a52-7d0e-4b8f-9a61-0c2d5e8b7f14

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": "paused",
  "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": "2026-10-26T14:30:00.000Z",
  "revokedAt": null
}

Errors

Code	HTTP status	When	What to do
`agent_revoked`	409	The agent is revoked.	Create a new agent instead.
`resource_not_found`	404	No agent with this ID exists in the organization.	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: validation_failed, api_version_unsupported, invalid_json, unsupported_media_type, authentication_required, api_key_invalid, idempotency_key_required, 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#

Pause an agent#

Errors#