Skip to main content
PATCH
/
v1
/
agents
/
{id}
Update an agent
curl --request PATCH \
  --url https://api.hq.zone/v1/agents/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "aliases": [
    "<string>"
  ],
  "avatar_url": "<string>",
  "cautions": [
    "<string>"
  ],
  "description": "<string>",
  "display_name": "<string>",
  "instructions": "<string>",
  "languages": [
    "<string>"
  ],
  "model": "<string>",
  "runtime_profile": "<string>",
  "slug": "<string>",
  "tone": "<string>",
  "verbosity": "<string>"
}
'
{
  "aliases": [
    "<string>"
  ],
  "cautions": [
    "<string>"
  ],
  "created_at": "2023-11-07T05:31:56Z",
  "delivery_mode": "<string>",
  "display_name": "<string>",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "instructions_is_default": true,
  "is_default": true,
  "languages": [
    "<string>"
  ],
  "runtime_profile": "<string>",
  "slug": "<string>",
  "status": "<string>",
  "avatar_url": "<string>",
  "description": "<string>",
  "instructions": "<string>",
  "model": "<string>",
  "tone": "<string>",
  "verbosity": "<string>"
}

Authorizations

​
Authorization
string
header
required

Personal Access Token. Send as Authorization: Bearer hq_pat_....

Path Parameters

​
id
string<uuid>
required

Agent id

Body

application/json
​
aliases
string[] | null
​
avatar_url
string | null

Some(Some(url)) sets, Some(None) clears, None leaves unchanged. Same explicit-null-vs-absent shape as description.

​
cautions
string[] | null
​
description
string | null

Explicit null clears the description; absent leaves it unchanged.

​
display_name
string | null
​
instructions
string | null

Same explicit-null-vs-absent shape as description - admin can clear the per-agent prompt (revert to platform baseline) vs. leave it unchanged.

​
languages
string[] | null
​
model
string | null

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
string | null
​
slug
string | null

New routing handle. On rename, the old slug auto-flips into aliases so existing @hq <old> references in chat history continue to route correctly. Same validation as on create (charset, reserved-token blocklist, collision check).

​
tone
string | null

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
string | null

Response

The updated agent

​
aliases
string[]
required
​
cautions
string[]
required

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
string<date-time>
required
​
delivery_mode
string
required
​
display_name
string
required
​
id
string<uuid>
required
​
instructions_is_default
boolean
required

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
boolean
required
​
languages
string[]
required

BCP-47 language codes. The first is the default; subsequent entries are explicit fallbacks. Empty = no language pin (LLM follows the user's language).

​
runtime_profile
string
required
​
slug
string
required
​
status
string
required
​
avatar_url
string | null

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).

​
description
string | null
​
instructions
string | null

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.

​
model
string | null

Selected model slug (e.g. claude-opus-4-8). NULL = the runtime's platform default. Must belong to runtime_profile (billing C).

​
tone
string | null

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
string | null

One of concise | balanced | detailed (or NULL = unset). Drives a canonical "Default to brief / balanced / detailed responses" sentence in the system prompt.