Avatars

Avatars are workspace-scoped resources that hold a face image and optional AI persona config. Each POST /versions creates an immutable snapshot. Pass the resulting version ID as avatar_ref when creating a session.

Try it →

List avatars

GET /api/v1/workspaces/{wsId}/avatars

Required scope: avatars:read

Response 200

{
  "data": [
    {
      "id": "019...",
      "workspace_id": "019...",
      "name": "My avatar",
      "kind": "stock",
      "current_version_id": "019...",
      "status": "active",
      "deleted_at": null,
      "region_tag": "us",
      "created_at": 1719000000,
      "updated_at": 1719000000
    }
  ]
}

---

Create an avatar

POST /api/v1/workspaces/{wsId}/avatars

Required scope: avatars:write

Request body

{ "name": "My avatar", "kind": "stock" }

Field	Required	Description
name	Yes	Human-readable label.
kind	No	Defaults to "stock".

Response 201 — avatar object as shown in list above.

---

Get an avatar

GET /api/v1/workspaces/{wsId}/avatars/{avatarId}

Required scope: avatars:read

Response 200 — single avatar object.

---

List avatar versions

GET /api/v1/workspaces/{wsId}/avatars/{avatarId}/versions

Required scope: avatars:read

Response 200

{
  "data": [
    {
      "id": "019...",
      "avatar_id": "019...",
      "version_number": 1,
      "image_r2_key": "workspaces/.../image",
      "system_prompt": "You are a helpful assistant.",
      "config_json": null,
      "created_by": "019...",
      "created_at": 1719000000
    }
  ]
}

---

Create an avatar version

POST /api/v1/workspaces/{wsId}/avatars/{avatarId}/versions

Required scope: avatars:write

Request body

{
  "system_prompt": "You are a helpful assistant.",
  "config_json": {}
}

Response 201

{
  "id": "019...",
  "avatar_id": "019...",
  "version_number": 1,
  "image_r2_key": null,
  "system_prompt": "You are a helpful assistant.",
  "config_json": null,
  "created_by": "019...",
  "created_at": 1719000000,
  "upload_url": "/api/v1/workspaces/{wsId}/avatars/{avatarId}/versions/{id}/upload"
}

After creating the version, PUT the avatar image bytes to upload_url:

curl -X PUT https://api.casola.ai{upload_url} \
  -H "Authorization: Bearer $CASOLA_API_KEY" \
  -H "Content-Type: image/png" \
  --data-binary @avatar.png

Once the image is uploaded, image_r2_key is set and the version becomes the avatar’s current_version_id. Pass this version’s id as avatar_ref in a session.