Update agent

Update an existing agent. Supports partial updates — only provided fields are changed. Both config and externalConfig are merged onto the stored values, so a partial write preserves keys it omits (notably externalConfig.protocol and externalConfig.cachedAgentCard). To REMOVE a value, send it explicitly as null: a null field clears that field, and externalConfig: null clears the whole object. Nested values replace atomically — sending auth replaces the entire auth block, so switching auth type cannot reuse the previous credential. Agent management responses return a configured auth.credentials value as <redacted>; echoing that placeholder on an update preserves the stored credential only when auth.type is unchanged. Repointing an external agent (endpoint, agentCardUrl or protocol) discards the cached agent card, which is re-fetched by POST /agents/{id}/refresh-agent-card. Moving externalConfig.endpoint to a different host additionally requires re-sending externalConfig.auth: a stored credential is never carried to a host it was not configured against, so a repoint that omits auth is rejected with 400.

Authentication

AuthorizationBearer
API key or Clerk session token

Path parameters

idstringRequired

Request

This endpoint expects an object.
agentTypeenumOptional
Allowed values:
claudeManagedConfigobjectOptional
configobjectOptional
descriptionstringOptional
externalConfigobject or nullOptional
iconstringOptional<=50 characters
maxTurnsintegerOptional1-100
namestringOptional>=1 character
primaryFlowIdanyOptionalDeprecated

primaryFlowId is retired: primary-flow agents were removed (ADR 0024). Attach the flow to the agent as a runtime tool ({ toolType: ‘flow’, flowId }) or dispatch the flow directly via POST /v1/dispatch.

Response

Agent updated
agentTypestring
claudeManagedConfigmap from strings to any or null
configmap from strings to any or null
configHashstring or null
createdAtstring
descriptionstring or null
draftVersionIdstring or null
externalConfigmap from strings to any or null

External-agent configuration. Configured auth.credentials values are write-only and returned as <redacted>, never plaintext.

healthStatusstring or null
iconstring or null
idstring
lastHealthCheckAtstring or null
lastModifiedSourcestring or null
namestring
organizationIdstring or null
publishedVersionIdstring or null
statusstring
updatedAtstring
userIdstring
_warningslist of stringsOptional
dashboardUrlstringOptional
sandboxCapabilityIssueslist of objectsOptional

Errors

400
Bad Request Error
401
Unauthorized Error
402
Payment Required Error
403
Forbidden Error
404
Not Found Error
500
Internal Server Error