---
title: "Upload an agent avatar image"
method: POST
path: "/uploads/agents/{agent_id}/avatar"
tags: ["Uploads"]
---

# Upload an agent avatar image

`POST /uploads/agents/{agent_id}/avatar`

## Request

- Base URL: `https://api-docs.jackhamr.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api-docs.jackhamr.ai/uploads/agents/{agent_id}/avatar`
- Auth: none declared

Upload an image and set it as the agent's avatar.

Stores the uploaded bytes in the same ``app/static/avatars``
directory the internal ``agent_avatars`` router uses, persists an
:class:`~app.models.agent_avatar.AgentAvatar` row, and links it to
the agent via ``tags["avatar_id"]`` (the convention every avatar
lookup in the codebase reads). Returns the updated agent with the
resolved ``avatar_image_url``.

Org scope: the agent must belong to the caller's org; a wrong-org
agent surfaces as 404 so existence is not leaked across org
boundaries. Requires the ``owner`` or ``admin`` org role.

## Path parameters

- `agent_id` string, required

## Response `200`

Successful Response

- AgentOut: An agent as returned by ``GET/POST /api/v1/agents``.
  - `id` string, required
  - `organization_id` string, required
  - `name` string, required
  - `description` string, nullable
  - `status` string, required
  - `owner_user_id` string, nullable
  - `allow_cloning` boolean
  - `visible_to_org` boolean
  - `cores` integer, nullable
  - `memory` integer, nullable
  - `disk_size` integer, nullable
  - `template_id` string, nullable
  - `os_template` string, nullable
  - `size_preset_id` string, nullable
  - `sort_order` integer
  - `is_board_clone` boolean
  - `clone_of_agent_id` string, nullable
  - `avatar_image_url` string, nullable
  - `avatar_color` string, nullable
  - `subtitle` string, nullable
  - `tags` object, nullable
  - `metadata` object, nullable
  - `subagent_max_iterations` integer, nullable
  - `error_message` string, nullable
  - `last_error_at` string, date-time, nullable
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `provisioned_at` string, date-time, nullable
  - `started_at` string, date-time, nullable
  - `stopped_at` string, date-time, nullable
  - `hibernated_at` string, date-time, nullable

## Other responses

- `422`: Validation Error

---

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