Skip to main content
POST
/
v1
/
agents
/
{id}
/
avatar
Upload an agent avatar
curl --request POST \
  --url https://api.hq.zone/v1/agents/{id}/avatar \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "body_b64": "<string>",
  "content_type": "<string>",
  "filename": "<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
​
body_b64
string
required
​
content_type
string
required
​
filename
string
required

Response

The agent, with its new avatar_url

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