---
title: "List saved characters"
method: GET
path: "/characters"
tags: ["Characters"]
---

# List saved characters

`GET /characters`

## Request

- Base URL: `https://api.braiv.co/v1`
- URL: `https://api.braiv.co/v1/characters`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-Api-Key`

Returns Studio-saved thumbnail character profiles for the API key's
personal or workspace library (up to 100). Create characters in Studio;
this API does not create or update them. Pass `id` as `characterId` on
thumbnail create. Required scope: `videos:read`.

## Response `200`

Saved characters in the caller's library.

- CharacterList
  - `characters` Character[], required: Saved characters in the caller's library.
    - `id` string, required: Saved character profile ID (use as `characterId` on thumbnail create).
    - `name` string, required: Display name from Studio.
    - `readyForThumbnailGeneration` boolean, required: True when the profile has enough reference images for generation.
    - `characterType` 'thumbnail-reference' | 'lora' | 'hybrid': Studio character storage mode when known.
    - `referenceImageIds` string[], required: Ordered reference image ids stored on the profile.
    - `referenceImages` object, required: Map of reference image id to stored download URL.

## Other responses

- `401`: A supported authentication header is missing or contains an invalid Public API key.
- `403`: Authentication succeeded, but the required scope, workspace role, or resource permission is missing.
- `429`: The API key exceeded its allowed concurrency or request rate. Retry after in-flight work completes or the limit resets.
- `500`: An unexpected server error occurred.

---

[API](https://skmtc.dev/braiv/apis/braiv-public-api.md) - [All operations](https://skmtc.dev/braiv/apis/braiv-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/braiv/apis/braiv-public-api/revisions/8ed0fd0d0a6f?raw)