Skip to main content
POST
Resume a paused agent
The reference panel describes the current v3 operation. The notes below describe its v2 compatibility API. Follow the v3 request schema for current calls: v3 can move identifiers from the body or query into the URL. Keep the v2 method, path, and payload together when using the compatibility API.

v2 compatibility notes

POST /api/v2/agents/resume resumes a paused agent. The body is exactly { id, reason }: id is the agent’s slug (agentId) and reason is 8 to 1,000 characters, recorded on the audit event. The audit event names the key’s owner for a Personal key, or the External App.

Authority

You need switches:use at the agent’s home org unit, and agents:read there to see the agent. A missing, PERSONAL, unhomed or unreadable agent is the same 404 resource_missing (Agent not found); an unavailable agent store is 500, never 404. Without switches:use at the home the answer is 403 permission_denied, recorded as a refused request. switches:use is never held by a Forge agent. Give it to a Personal key as an opt-in, short-expiry scope.

Status rules

The kill switch moves an agent only between active and paused, and to deprecated (terminated):
  • pause pauses only an active agent: a terminated (deprecated), archived, draft or other agent is refused with 409 invalid_state, so a pause then a resume never activates an agent that was not active. Pausing a paused agent changes nothing.
  • resume refuses a terminated or archived agent, and any agent that is not paused (a draft is published, never resumed), with 409 invalid_state. Resuming an active agent changes nothing.
  • terminate refuses an archived agent with 409 invalid_state. Terminating a terminated agent changes nothing.
A call that changes nothing answers 200 with changed: false and writes no audit event.

Replay

With an Idempotency-Key, a repeat of the same request within 24 hours returns the recorded answer only while the slug still names the same agent definition, you may still read the agent at its home, and you still hold the route’s permission there (the agent_write replay rule). Otherwise the repeat is 409 conflict and the write never runs twice. See Agent administration.

Authorizations

Authorization
string
header
required

An External App: the JWT it obtains from POST /oauth/token with OAuth2 client_credentials. Pass as Authorization: Bearer <jwt>. An app's static companion key also authenticates as the app, but is deprecated and is not protected by Idempotency-Key.

Headers

Idempotency-Key
string

1–255 printable ASCII characters (0x21–0x7E, no spaces), scoped to the calling credential. A repeat with the same key and request never runs the write again, a 5xx included: once the operation's permissions pass again it answers the identical status and body of the first response (Idempotent-Replayed: true, also sent as Idempotency-Replayed: true), unless the operation's own replay policy withholds it; a first response that was not stored (over 32 KiB, or carrying a one-time secret) answers its first status with only data.id (Idempotency-Replay-Disclosure: id-only) when it named one; otherwise 409 idempotency_result_unavailable; a repeat while the first is still running is 409 idempotency_key_in_flight, and the same key with a different request is 422 idempotency_key_reuse. Honoured for External App JWTs and platform and Personal keys; an External App's static companion key is not protected.

Required string length: 1 - 255

Path Parameters

agentId
string
required

The agent's slug (agentId).

Minimum string length: 1

Body

application/json

id is the agent's slug. reason is 8 to 1000 characters.

reason
string
required

Why, recorded on the audit event.

Required string length: 8 - 1000

Response

Resume a paused agent

data
object
required
meta
object
required