Apps API · Avatars
Avatars: 2 endpoints
POST /api/v1/avatars/uploads/finalize
Finalize avatar upload
Scope: org:me:write · Called with: appToken · operationId: finalize-avatar-upload
Required app scope: org:me:write.
Finalizes an avatar upload the caller prepared in the current organization and returns avatar_url ({api_origin}/api/public/avatars/{org_id}/{artifact_id}, where api_origin is this deployment's public API origin), a long-lived URL with no signature or expiry. Nothing is saved yet: send avatar_url to PATCH /api/v1/me (own avatar) or PUT /api/v1/agents/{member_id}/avatar (Agent). 403 AVATAR_FORBIDDEN when the artifact is not the caller's avatar upload; 400 AVATAR_INVALID when it is not finalizable. Response wrapped in standard envelope.
Request body
application/json · FinalizeAvatarUploadInputBody
| Field | Type | Required | Description |
|---|---|---|---|
artifact_id |
string (uuid) | yes | Prepared avatar artifact UUID |
session_id |
string (uuid) | yes | Prepared upload-session UUID |
Responses
200OK —application/json·DataResponseAvatarUploadFinalizedBodydefaultError —application/problem+json·D8Error
POST /api/v1/avatars/uploads/prepare
Prepare avatar upload
Scope: org:me:write · Called with: appToken · operationId: prepare-avatar-upload
Required app scope: org:me:write.
Creates an avatar image artifact owned by the caller and returns a presigned PUT. Any member of the current organization may upload; who may SAVE the avatar is checked when avatar_url is written. content_type must be image/png, image/jpeg or image/webp and size_bytes 1..5242880, else 400 AVATAR_INVALID (the client crops to a square before upload). PUT the bytes to upload_url with headers, then call finalize. 503 AVATAR_NOT_CONFIGURED when avatar storage is not configured on this deployment. Response wrapped in standard envelope.
Request body
application/json · PrepareAvatarUploadInputBody
| Field | Type | Required | Description |
|---|---|---|---|
content_type |
string | yes | Image MIME type: image/png, image/jpeg or image/webp |
filename |
string | yes | Original image filename (plain name, 1..255 characters) |
size_bytes |
integer (int64) | yes | Image size in bytes, 1..5242880 (5 MiB) |
Responses
200OK —application/json·DataResponseAvatarUploadPreparedBodydefaultError —application/problem+json·D8Error
