---
title: "Update agent"
method: PATCH
path: "/agents/{agentId}"
tags: ["Agents"]
---

# Update agent

`PATCH /agents/{agentId}`

Update an agent's mutable fields; a slug renames the handle and can never be cleared

## Path parameters

- `agentId` string, required — Agent ID (agt_*).

## Headers

- `Idempotency-Key` string, required
- `X-Agent-ID` string, nullable
- `X-Instance-ID` string, nullable

## Request body

- object
  - `data` object, required
    - `attributes` object, required
      - `name` string, nullable — Agent display name.
      - `description` string, nullable — Agent description.
      - `slug` string — Agent-specific part of the handle, such as support in @acme-support. Renames the handle; omission leaves it unchanged. Handles cannot be cleared.
      - `limits` object, nullable — Agent spending limits. Null clears all limits; omission leaves them unchanged. Within the object, a null or omitted window clears that limit.
        - `perTransaction` integer, nullable — Per-transaction spending limit in cents, or null for no limit.
        - `perDay` integer, nullable — Daily spending limit in cents, or null for no limit.
        - `perMonth` integer, nullable — Monthly spending limit in cents, or null for no limit.

## Response `200`

Successful Response

- object
  - `data` object, required
    - `type` 'agent', required
    - `id` string, required — Agent ID (agt_*).
    - `attributes` object, required
      - `name` string, required — Agent display name.
      - `description` string, nullable, required — Agent description.
      - `handle` string, nullable, required — Agent handle, such as @acme-support, or null if none is configured.
      - `status` 'ACTIVE' | 'REVOKED', required — Agent status.
      - `limits` object, nullable, required — Spend caps for actions this agent initiates on its owner's party.
        - `perTransaction` integer, nullable — Per-transaction spending limit in cents, or null for no limit.
        - `perDay` integer, nullable — Daily spending limit in cents, or null for no limit.
        - `perMonth` integer, nullable — Monthly spending limit in cents, or null for no limit.
      - `createdAt` string, date-time, nullable, required — When this agent was created.
      - `createdBy` string, nullable, required — User who created this agent (usr_*).
      - `lastActiveAt` string, date-time, nullable, required — When the agent last authenticated, or null if it has never authenticated.
    - `relationships` object, required
      - `party` object, required — Party that owns the agent.
        - `data` object, required — Related resource identifier.
          - `type` 'party', required
          - `id` string, required

## Other responses

- `400` — Validation Error
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found. Returned when the resource does not exist, or when it exists but is not accessible to your account. The two cases are intentionally indistinguishable, so that resource IDs cannot be enumerated by probing.
- `409` — Conflict
- `422` — Validation Error
- `428` — Precondition Required
- `429` — Too Many Requests
- `500` — Internal Server Error
- `501` — Not Implemented
- `502` — Bad Gateway
- `503` — Service Unavailable

---

[API](https://skmtc.net/natural/apis/natural-api.md) · [All operations](https://skmtc.net/natural/apis/natural-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/natural/natural-api/versions/0bb9c54b1f61/schema)