> ## Documentation Index > Fetch the complete documentation index at: https://docs.hq.zone/llms.txt > Use this file to discover all available pages before exploring further. # Update an agent > Updates the named agent's editable fields (slug, display name, description, instructions, tone, verbosity, cautions, languages, aliases, runtime profile, model, avatar URL) and returns the updated agent; only the fields you send are changed, and an explicit null clears nullable fields back to their default. Renaming the slug automatically preserves the old slug as an alias so existing references still route. Validation matches creation (slug/alias rules and collision checks); returns 404 if the agent is not in the caller's workspace. Admin only. ## OpenAPI ````yaml PATCH /v1/agents/{id} openapi: 3.1.0 info: title: HQ API description: >- Public HTTP API for HQ. Authenticate with a Personal Access Token (`Authorization: Bearer hq_pat_...`) for server-side integrations, or an OAuth 2.1 authorization-code + PKCE flow for browser apps acting on a user's behalf. Both grant from the same resource:action scope vocabulary; an endpoint's required scope is listed under its `security`. license: name: Apache-2.0 identifier: Apache-2.0 version: 1.0.0 servers: - url: https://api.hq.zone description: HQ API (production) security: [] tags: - name: me description: The signed-in user's own account - name: conversations description: Conversations and their messages - name: documents description: The content-addressed documents library - name: schedules description: Scheduled prompts and recurring tasks - name: agents description: Agents, their skills and integrations - name: memory description: What the assistant remembers (L5 governance) - name: tokens description: Personal Access Token management - name: billing description: Usage and billing - name: notifications description: In-app notification center - name: admin description: Workspace administration - name: integrations description: Workspace integrations (Slack, MCP, skills) - name: onboarding description: New-workspace onboarding wizard - name: auth description: Sign-in, sessions, and OAuth paths: /v1/agents/{id}: patch: tags: - agents summary: Update an agent description: >- Updates the named agent's editable fields (slug, display name, description, instructions, tone, verbosity, cautions, languages, aliases, runtime profile, model, avatar URL) and returns the updated agent; only the fields you send are changed, and an explicit null clears nullable fields back to their default. Renaming the slug automatically preserves the old slug as an alias so existing references still route. Validation matches creation (slug/alias rules and collision checks); returns 404 if the agent is not in the caller's workspace. Admin only. operationId: update_agent parameters: - name: id in: path description: Agent id required: true schema: type: string format: uuid requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateReq' required: true responses: '200': description: The updated agent content: application/json: schema: $ref: '#/components/schemas/AgentRow' '400': description: Invalid slug / alias conflict / bad field '404': description: No such agent in this workspace security: - bearer_pat: - admin - oauth2: - admin components: schemas: UpdateReq: type: object properties: aliases: type: - array - 'null' items: type: string avatar_url: type: - string - 'null' description: |- `Some(Some(url))` sets, `Some(None)` clears, `None` leaves unchanged. Same explicit-null-vs-absent shape as description. cautions: type: - array - 'null' items: type: string description: type: - string - 'null' description: Explicit `null` clears the description; absent leaves it unchanged. display_name: type: - string - 'null' instructions: type: - string - 'null' description: |- Same explicit-null-vs-absent shape as description - admin can clear the per-agent prompt (revert to platform baseline) vs. leave it unchanged. languages: type: - array - 'null' items: type: string model: type: - string - 'null' description: >- `Some(Some(slug))` sets the model, `Some(None)` clears to the runtime default, `None` leaves unchanged. Validated against the registry for the effective runtime (billing C). runtime_profile: type: - string - 'null' slug: type: - string - 'null' description: |- New routing handle. On rename, the old slug auto-flips into `aliases` so existing `@hq ` references in chat history continue to route correctly. Same validation as on create (charset, reserved-token blocklist, collision check). tone: type: - string - 'null' description: |- Personality knobs - same explicit-null-vs-absent shape for tone + verbosity (single-value enums). `cautions` and `languages` are arrays: Some(vec) replaces, None leaves. verbosity: type: - string - 'null' AgentRow: type: object required: - id - slug - display_name - instructions_is_default - cautions - languages - aliases - runtime_profile - delivery_mode - is_default - status - created_at properties: aliases: type: array items: type: string avatar_url: type: - string - 'null' description: |- Absolute URL of the avatar shown next to this agent's messages. NULL = use the Slack app's default icon for now (fine for legacy single-agent tenants). cautions: type: array items: type: string description: |- Free-form short phrases the agent should avoid talking about. Composed as "Be careful around: X, Y, Z" in the system prompt. Empty = no caution block. created_at: type: string format: date-time delivery_mode: type: string description: type: - string - 'null' display_name: type: string id: type: string format: uuid instructions: type: - string - 'null' description: |- Admin-editable system-prompt for this agent. NULL = use the platform baseline only (the legacy generalist behaviour). Plumbed through to `router_client::compose_system_prompt` which sandwiches it between the Slack-formatting baseline and the identity-pin footer. instructions_is_default: type: boolean description: |- True iff `instructions` is still the platform-seeded value (admin hasn't customised or tailored yet). The admin UI uses this to surface a "your agent is still on the default - click Tailor" banner. Any PATCH that writes instructions flips this false; the seed migrations set it true on creation. is_default: type: boolean languages: type: array items: type: string description: |- BCP-47 language codes. The first is the default; subsequent entries are explicit fallbacks. Empty = no language pin (LLM follows the user's language). model: type: - string - 'null' description: |- Selected model slug (e.g. `claude-opus-4-8`). NULL = the runtime's platform default. Must belong to `runtime_profile` (billing C). runtime_profile: type: string slug: type: string status: type: string tone: type: - string - 'null' description: |- One of `formal | friendly | direct | casual` (or NULL = unset → no tone pin in the system prompt). Orthogonal to role; admin choice, not inferrable from "you're a CFO". verbosity: type: - string - 'null' description: |- One of `concise | balanced | detailed` (or NULL = unset). Drives a canonical "Default to brief / balanced / detailed responses" sentence in the system prompt. securitySchemes: bearer_pat: type: http scheme: bearer bearerFormat: hq_pat description: 'Personal Access Token. Send as `Authorization: Bearer hq_pat_...`.' oauth2: type: oauth2 flows: authorizationCode: authorizationUrl: https://app.hq.zone/v1/oauth/authorize tokenUrl: https://api.hq.zone/v1/oauth/token refreshUrl: https://api.hq.zone/v1/oauth/token scopes: admin: Administer the workspace (users, settings, integrations) agents:read: View the agents in your workspace agents:write: Create and configure agents billing:read: View usage and billing information conversations:read: Read your conversations and their messages conversations:write: Start conversations and send messages on your behalf documents:read: Read your documents library documents:write: Upload and manage documents in your library memory:read: Read what the assistant remembers about you memory:write: Correct or delete what the assistant remembers schedules:read: View your scheduled tasks schedules:write: Create and manage scheduled tasks tables:read: Read your tables and their rows tables:write: Create tables and add, edit, or delete rows ````