---
title: "Update agent name"
method: PUT
path: "/agents/{agent_id}"
tags: ["Agents"]
---

# Update agent name

`PUT /agents/{agent_id}`

## Request

- Base URL: `https://api.mnemom.ai/v1`
- URL: `https://api.mnemom.ai/v1/agents/{agent_id}`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-Mnemom-Api-Key`

Update the name of an agent you own.

## Path parameters

- `agent_id` string, required

## Request body

- object
  - `name` string, required: New agent name. 2-32 characters, alphanumeric and hyphens only.

## Response `200`

Updated agent record

- Agent: An agent. GET /v1/agents/{id} returns one of TWO projections by authorization: an ORGANIZATION-MEMBER (owner) caller receives the full agent row (all fields below); a NON-OWNER receives a reduced public projection (id, name, claimed, created_at, last_seen, status, avatar_url). additionalProperties is left open because the owner row is the full DB row and grows as agent-settings columns are added (ADR-053 / proof / DDR); over-constraining it would 500 the endpoint on the next migration under /v1 response enforcement.
  - `id` string
  - `claimed` boolean: Public projection only: whether the agent has been claimed by a user.
  - `avatar_url` string, nullable
  - `claimed_by` string, nullable: Owner projection: user id that claimed the agent.
  - `created_by` string, nullable: Owner projection: user id that created the agent (provenance).
  - `org_id` string, nullable: Owner projection: the agent's org binding (ADR-062 authz boundary).
  - `agent_proof_hash` string, nullable: Owner projection: captured hash_proof of the bound key (mig 263).
  - `agent_proof_captured_at` string, date-time, nullable
  - `deleted_at` string, date-time, nullable: Owner projection: soft-delete timestamp (null when live).
  - `agent_hash` string: First 16 hex chars of `SHA256(apiKey + '|' + agentName)` for named agents, or `SHA256(apiKey)` for unnamed singleton agents. The gateway computes the same value on each request and uses it as the lookup key. See [Agent Identity](https://docs.mnemom.ai/concepts/agent-identity#agent_hash--the-canonical-identity-hash).
  - `user_id` string, nullable
  - `email` string, nullable
  - `claimed_at` string, date-time, nullable
  - `last_seen` string, date-time, nullable
  - `name` string, nullable: Agent name (2-32 chars, alphanumeric + hyphens). Present on all list and get responses.
  - `containment_status` 'active' | 'paused' | 'killed', nullable: Containment state of the agent (ADR-053).
  - `key_prefix` string, nullable: First 8 chars of the bound API key hash — useful for key-rotation debugging.
  - `status` 'active' | 'offline'
  - `caller` 'anonymous' | 'authenticated' | 'org_member': Self-describing caller context for THIS response. `org_member` callers receive the full owner record (all fields here); `anonymous`/`authenticated` (non-member) callers receive the reduced public projection (id, name, claimed, created_at, last_seen, status, avatar_url, caller). The differing field set is GOVERNED by this value — read it instead of inferring why a field is absent.
  - `public` boolean: Identity-record visibility axis — whether the agent's IDENTITY RECORD is publicly discoverable. This is DISTINCT from reputation visibility: every registered agent's reputation is public by accountability standard (see `ReputationScore.visibility`). `public` here governs only the identity record, never the Trust Rating.
  - `aip_enforcement_mode` 'observe' | 'enforce' | 'nudge', nullable
  - `billing_account_id` string, nullable
  - `created_at` string, date-time
  - `groups` object[]: Active groups this agent belongs to, name-ordered; `[]` when none. Present on org-fleet rows (GET /v1/orgs/{org_id}/agents). Archived groups are excluded.
    - `id` string, required
    - `name` string, required
    - `color` string, nullable, required: Group color (hex, e.g. `#0d9488`); `null` when unset.

## Other responses

- `400`: Bad request
- `401`: Authentication required
- `403`: Forbidden
- `404`: Resource not found
- `429`: Rate-limit exceeded. The global per-IP limiter (100 requests/minute, applied to every `/v1/*` route) rejected this request. Back off until the window resets — `Retry-After` carries the cooldown in seconds and `X-RateLimit-Reset` the absolute reset time.
- `500`: Server error — request was well-formed but the server failed to fulfill it. Typically a downstream dependency (DB / RPC / external API) returned an unexpected error.

---

[API](https://skmtc.dev/mnemom/apis/mnemom-api.md) · [All operations](https://skmtc.dev/mnemom/apis/mnemom-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mnemom/apis/mnemom-api/revisions/274b7a6ea182?raw)