---
title: "Update an agent"
method: PATCH
path: "/api/v2/agents/{agent_id}"
tags: ["Agents"]
---

# Update an agent

`PATCH /api/v2/agents/{agent_id}`

## Request

- Base URL: `https://console.jumpcloud.com`
- URL: `https://console.jumpcloud.com/api/v2/agents/{agent_id}`
- Auth: API key in header `x-api-key`
- TypeScript: <https://skmtc.dev/jumpcloud/apis/jumpcloud-console-api/docs/api/v2/agents/:agent_id/patch.ts> (a function with typed inputs; its response is checked against the schema)

Updates an agent in your organization. Omitted fields are left unchanged.

## Path parameters

- `agent_id` string, required

## Headers

- `x-org-id` string

## Request body

- AgentUpdateRequest: Fields for updating an agent. Include at least one recognized field; omitted fields are left unchanged. An empty object fails schema validation (`minProperties`) and returns HTTP 400. JSON `null` on a string field fails type validation and returns HTTP 400. Empty `name`, `email`, or `ownerId` values are not accepted (HTTP 400). Set `description` to an empty string to clear it. Unrecognized properties are ignored; a body with no recognized mutable fields returns HTTP 400. Submitted `name`, `description`, and `email` values are trimmed of leading and trailing whitespace before apply.
  - `name` string: Agent name
  - `email` string, email: Company email address for this agent
  - `description` string: Free-text description of this agent
  - `ownerId` string: ID of the human user who will own this agent. Must be in the same organization. Must be a non-null ID when present.

## Response `200`

Agent updated successfully

- Agent: An agent — a non-human identity that can access applications assigned to it. Properties marked read-only are returned on read responses and must not be sent on create or update.
  - `id` string, required: Agent ID (24-character hexadecimal string).
  - `organizationId` string, required: Organization ID (24-character hexadecimal string).
  - `name` string, required: Agent name
  - `description` string: Free-text description of this agent
  - `email` string, email, required: Company email address for this agent
  - `ownerId` string, nullable: ID of the human user who owns this agent. Required at creation; becomes null only if the owning user is later deleted.
  - `state` 'active' | 'suspended', required: Lifecycle state (`active` or `suspended`).

## Other responses

- `400`: Bad request — validation failure. The `status` field carries a stable machine code in lowerCamelCase (aligned with JSON field names); `message` describes the failure for humans. Common codes include `nullName`, `invalidName`, `invalidEmail`, `invalidOwnerId`, `invalidOwner`, `stateNotUpdatable`, `ownerIdClearForbidden`, and `emptyPatch`. Including a read-only property from [Agent](#componentschemasagent) also returns HTTP 400.
- `401`: Unauthenticated
- `404`: Not Found
- `409`: An agent with a conflicting attribute already exists (for example email)
- `default`: Unexpected error

---

[API](https://skmtc.dev/jumpcloud/apis/jumpcloud-console-api.md) - [All operations](https://skmtc.dev/jumpcloud/apis/jumpcloud-console-api/llms.txt) - [OpenAPI document](https://skmtc.dev/jumpcloud/apis/jumpcloud-console-api/revisions/f396d9271b46?raw)