> ## Documentation Index > Fetch the complete documentation index at: https://anam.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # list personas > Returns a list of all personas ## OpenAPI ````yaml https://api.anam.ai/swagger.json get /v1/personas openapi: 3.1.0 info: title: Anam AI API version: '1.0' servers: - url: https://api.anam.ai description: Anam API security: - BearerAuth: [] tags: - name: Sessions - name: Avatar Videos - name: Meetings - name: Personas - name: Avatars - name: Voices - name: Pronunciation Dictionaries - name: LLMs - name: Knowledge - name: Tools - name: Share Links - name: Engine paths: /v1/personas: get: tags: - Personas summary: list personas description: Returns a list of all personas operationId: listPersonas parameters: - in: query name: page schema: type: integer minimum: 1 default: 1 description: Page number for pagination - in: query name: perPage schema: type: integer minimum: 1 maximum: 100 default: 10 description: Number of items per page - in: query name: search schema: type: string description: filter personas by name responses: '200': description: Successfully retrieved personas content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/PersonaSummary' meta: $ref: '#/components/schemas/Pagination' examples: default: $ref: '#/components/examples/PersonaListResponse' '401': description: Unauthorized - Invalid or missing API key '403': description: Forbidden - API key lacks the required permission '500': description: Server error '503': description: >- The API key could not be checked because of a temporary server problem. The key may be valid; retry after `Retry-After` seconds. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/ServiceUnavailableError' components: schemas: PersonaSummary: type: object description: >- Trimmed persona shape returned by the list endpoint. For the full shape use `GET /v1/personas/{id}`. properties: id: type: string format: uuid description: Unique identifier for the persona. name: type: string description: Human-readable name of the persona. description: type: string description: >- Free-form description of the persona. Empty string if none was provided. personaPreset: type: string deprecated: true description: >- Deprecated. Name of the legacy preset an older persona was created from, or an empty string. Presets can no longer be set; use `avatarId` and `voiceId`. avatar: oneOf: - $ref: '#/components/schemas/Avatar' - type: 'null' description: Avatar currently attached to the persona, or `null` if none. voice: oneOf: - $ref: '#/components/schemas/Voice' - type: 'null' description: Voice currently attached to the persona, or `null` if none. voiceSpeed: type: - number - 'null' description: Speech rate multiplier applied to the voice. isDefaultPersona: type: boolean description: >- Whether this is a built-in default persona available to every organization. languageCode: type: string description: >- Supported ISO 639 language code override (including "yue" for Cantonese) for transcription, or `inherit` to fall back to the organization default. createdAt: type: string format: date-time description: Timestamp when the persona was created. updatedAt: type: string format: date-time description: Timestamp when the persona was last updated. Pagination: type: object description: >- Pagination metadata returned alongside the `data` array of every list endpoint. properties: total: type: integer description: Total number of items across all pages. lastPage: type: integer description: Number of the last page. currentPage: type: integer description: Number of the current page. perPage: type: integer description: Number of items per page. prev: type: - integer - 'null' description: Number of the previous page, or null if on the first page. next: type: - integer - 'null' description: Number of the next page, or null if on the last page. ServiceUnavailableError: type: object required: - error - message properties: error: type: string example: Service temporarily unavailable message: type: string example: We could not check your API key. Please retry shortly. Avatar: type: object description: A face preset that a persona can use as its visual representation. properties: id: type: string format: uuid description: Unique identifier for the avatar. displayName: type: string description: Human-readable name shown in the Lab and share links. variantName: type: string description: >- Name of the specific variant (e.g. lighting or pose) within the avatar family. imageUrl: type: string format: uri description: >- Still image of the avatar, framed exactly like `videoUrl`, `idleVideoUrl` and a landscape session (the default). Use it as the thumbnail, poster or loading image wherever a preview video or the live stream replaces it, and give the image and the video the same box, `object-fit` and `object-position` so the avatar doesn't move when they swap. For Cara 4 avatars this is the 1152x768 landscape crop (the same image as `landscapeImageUrl`). Cara 4 avatars used to return their square source image here; that image is now `sourceImageUrl`. Empty when the avatar has no image yet, or when its images are not available through the API. May be a time-limited link; see `imageUrlsExpireAt`. sourceImageUrl: type: string format: uri description: >- The image the avatar was created from. For Cara 4 avatars it is square (1152x1152) and shows more of the scene than the 1152x768 crop that preview videos and sessions use, so the avatar appears to zoom in when a video or call replaces it. Don't use it as a thumbnail, poster or loading image next to `videoUrl` or a session; use `imageUrl`, `landscapeImageUrl` or `portraitImageUrl`. For legacy avatars it is the same landscape image as `imageUrl`. Empty when the avatar's images are not available through the API. May be a time-limited link; see `imageUrlsExpireAt`. landscapeImageUrl: type: - string - 'null' format: uri description: >- Still image cropped exactly as the engine frames landscape (1152x768) output, which is also the framing of `videoUrl` and `idleVideoUrl`. Use it with landscape sessions (the default) and preview videos. For avatars with legacy landscape source images this is the source image. `null` when the avatar's images are not available through the API. May be a time-limited link; see `imageUrlsExpireAt`. portraitImageUrl: type: - string - 'null' format: uri description: >- Still image cropped exactly as the engine frames portrait (768x1152) output. Use it as the poster for a session started with portrait `videoWidth`/`videoHeight`. Preview videos are landscape, so don't swap this image for `videoUrl`. `null` when the avatar cannot render portrait output or its images are not available through the API. May be a time-limited link; see `imageUrlsExpireAt`. imageUrlsExpireAt: type: - string - 'null' format: date-time description: >- When set, `imageUrl`, `sourceImageUrl`, `landscapeImageUrl` and `portraitImageUrl` are time-limited links that stop working at this time; fetch the avatar again for fresh ones. They stay valid for at least an hour, and repeated requests within the same hour return the same links, so browsers can cache them. Treat them as credentials for those images, since anyone holding a link can load the image until it expires. `null` when the image URLs don't expire. videoUrl: type: - string - 'null' format: uri description: >- Signed URL for a verified muted MP4 preview of the avatar. Uses the idle loop if the talking preview is unavailable. Landscape (1152x768 for Cara 4 avatars, 720x480 for legacy avatars) and framed exactly like `imageUrl`, so pair it with `imageUrl` or `landscapeImageUrl`, not `sourceImageUrl`. The URL expires after 1 hour; re-fetch the avatar to get a fresh URL. `null` when the preview is unavailable or still generating. idleVideoUrl: type: - string - 'null' format: uri description: >- Signed URL for a muted idling-loop MP4 of the avatar, if one exists. Landscape and framed exactly like `imageUrl`, like `videoUrl`. The URL expires after 1 hour; re-fetch the avatar to get a fresh URL. `null` when unavailable or still generating. createdAt: type: string format: date-time description: Timestamp when the avatar was created. updatedAt: type: string format: date-time description: Timestamp when the avatar was last updated. createdByOrganizationId: type: - string - 'null' description: >- ID of the organization that created the avatar, or `null` for stock avatars. IDs may be either UUIDs or nanoid-style strings depending on when the organization was created. availableVersions: type: array items: type: string description: >- Avatar models this avatar can be used with. Pass one of these values as `avatarModel` when creating a persona or starting a session. activeVersion: type: - string - 'null' description: >- Avatar model used by default when no explicit `avatarModel` is requested. description: type: - string - 'null' description: >- AI-generated description of the avatar's appearance, setting, and style. `null` if metadata generation has not completed. displayTags: type: array items: type: string description: >- Curated tags describing the avatar. Empty array if metadata generation has not completed. renderStyle: type: string enum: - realistic - animated_3d - illustrated - unknown description: >- Render style of the avatar. `unknown` covers custom avatars and avatars whose metadata has not yet been generated. Voice: type: object description: A voice preset a persona can use for text-to-speech. properties: id: type: string format: uuid description: Unique identifier for the voice. displayName: type: string description: Human-readable name shown in the Lab. provider: type: string enum: - CARTESIA - ELEVENLABS - FISH_AUDIO description: Upstream TTS provider for this voice. providerVoiceId: type: - string - 'null' description: The upstream provider's identifier for the voice. providerModelId: type: - string - 'null' description: The upstream provider's model identifier used to generate speech. sampleUrl: type: - string - 'null' format: uri description: URL of a short audio preview of the voice. previewSampleUrl: type: - string - 'null' format: uri description: Alias for `sampleUrl`, kept for backwards compatibility. gender: type: - string - 'null' enum: - MALE - FEMALE - NEUTRAL - null description: Perceived gender of the voice, if categorised. country: type: - string - 'null' description: ISO 3166-1 alpha-2 country code representing the voice's accent. description: type: - string - 'null' description: Free-form description of the voice's character. displayTags: type: array items: type: string description: Tags used to categorise the voice in the Lab UI. isZdr: type: boolean description: Whether this voice meets the Zero Data Retention requirements. createdByOrganizationId: type: - string - 'null' description: >- ID of the organization that created the voice, or `null` for stock voices. IDs may be either UUIDs or nanoid-style strings depending on when the organization was created. createdAt: type: string format: date-time description: Timestamp when the voice was created. updatedAt: type: string format: date-time description: Timestamp when the voice was last updated. examples: PersonaListResponse: summary: A paginated list of personas (trimmed shape) value: data: - id: 00000000-0000-0000-0000-000000000000 name: Cara description: A helpful assistant personaPreset: '' avatar: id: 071b0286-4cce-4808-bee2-e642f1062de3 displayName: Liv variantName: home imageUrl: https://lab.anam.ai/persona_thumbnails/liv_home.png videoUrl: https://example.com/avatar-preview.mp4?X-Amz-Signature=... createdAt: '2026-04-20T10:00:00.000Z' updatedAt: '2026-04-20T10:00:00.000Z' createdByOrganizationId: null availableVersions: - cara-3 activeVersion: cara-3 description: >- A friendly professional in a modern office setting, warm expression, business casual attire. displayTags: - professional - friendly - office renderStyle: realistic voice: id: de23e340-1416-4dd8-977d-065a7ca11697 displayName: Lucy - Fresh & Casual provider: ELEVENLABS providerVoiceId: lcMyyd2HUfFzxdCaC4Ta providerModelId: eleven_flash_v2_5 sampleUrl: >- https://newgxnc1uqs0jnqm.public.blob.vercel-storage.com/voice-samples/de23e340-1416-4dd8-977d-065a7ca11697/1760617899390.mp3 previewSampleUrl: >- https://newgxnc1uqs0jnqm.public.blob.vercel-storage.com/voice-samples/de23e340-1416-4dd8-977d-065a7ca11697/1760617899390.mp3 gender: FEMALE country: GB description: >- Energetic and youthful British voice, perfect for narrations and conversational agents. displayTags: - fast isZdr: true createdByOrganizationId: null createdAt: '2026-04-20T10:00:00.000Z' updatedAt: '2026-04-20T10:00:00.000Z' voiceSpeed: 1 isDefaultPersona: false languageCode: inherit createdAt: '2026-04-20T10:00:00.000Z' updatedAt: '2026-04-20T10:00:00.000Z' meta: total: 1 lastPage: 1 currentPage: 1 perPage: 10 prev: null next: null securitySchemes: BearerAuth: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.