> ## Documentation Index > Fetch the complete documentation index at: https://docs.protoface.com/llms.txt > Use this file to discover all available pages before exploring further. # Retrieve an avatar > Return a single avatar by id. ## OpenAPI ````yaml /openapi.json get /v1/avatars/{avatar_id} openapi: 3.1.0 info: description: > Create realtime avatar sessions. ### Authentication All `/v1/*` endpoints require a live API key: ``` Authorization: Bearer sk_live_... ``` Keys are minted in the dashboard and are scoped to a single environment (staging or prod). ### Idempotency `POST /v1/sessions` may include an `Idempotency-Key` header (any opaque string, <= 255 chars). Retries with the same key inside 24 hours return the first response. The header is optional. ### Errors Every non-2xx response is a JSON body of the form: ```json { "error": { "type": "invalid_request", "code": "transport.unsupported", "message": "transport.type=pipecat is not supported", "param": "transport.type", "request_id": "req_01HXY..." } } ``` Switch on `error.code` (stable lower_snake_case), not `error.message`. ### Pagination List endpoints use cursor pagination: ``` GET /v1/sessions?limit=20&starting_after=sess_01HXY... ``` Response shape: ```json { "object": "list", "data": [...], "has_more": true, "next_cursor": "sess_01HXY..." } ``` summary: Protoface — realtime avatar API for developers. title: Protoface API version: 0.1.0 servers: [] security: [] tags: - description: >- Create, retrieve, list, and end realtime avatar sessions. Sessions stream audio in and video out; their lifecycle drives billing. name: sessions - description: >- Avatar definitions. Includes platform stock avatars and customer-uploaded avatars. name: avatars - description: Blocking talking-avatar video generation from uploaded audio. name: videos - description: Aggregate usage for billing reconciliation. name: usage - description: >- Public platform metadata — currently just status. Unauthenticated. Internal load-balancer and task health probes exist on this host but are not part of the documented surface. name: platform - description: Direct media sessions for the `pipecat-protoface` avatar video service. name: pipecat - description: Public billing plan metadata for signup and pricing UI. name: billing paths: /v1/avatars/{avatar_id}: get: tags: - avatars summary: Retrieve an avatar description: Return a single avatar by id. operationId: get_avatar parameters: - description: Stable `av_…` avatar id. in: path name: avatar_id required: true schema: description: Stable `av_…` avatar id. title: Avatar Id type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/Avatar' description: Successful Response '401': content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' description: Missing or invalid API key. '404': content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' description: No avatar with that id. '422': content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' description: Request body or parameters failed validation. security: - ApiKey: [] components: schemas: Avatar: additionalProperties: false description: >- Public Avatar resource returned by `GET /v1/avatars` and `GET /v1/avatars/{id}`. examples: - created_at: '2026-01-01T00:00:00Z' id: av_stock_001 is_demo: true name: Stock Avatar 001 object: avatar runtime_type: avtr1 status: ready voice: cedar properties: created_at: format: date-time type: string custom_instructions: anyOf: - type: string - type: 'null' description: >- Preferred managed-conversation instructions for this avatar, when configured. failure_reason: anyOf: - type: string - type: 'null' description: >- Human-readable reason the build failed (e.g. `No face detected in source image.`). Only set while `status` is `failed`. id: description: >- Stable `av_…` avatar id. Platform stock avatars use fixed ids such as `av_stock_001`; customer avatars use generated ids. type: string is_demo: description: True for platform stock avatars (e.g. `av_stock_001`). type: boolean name: type: string object: const: avatar default: avatar type: string runtime_type: description: Runtime that serves this avatar (e.g. `mock`, `avtr1`). type: string status: $ref: '#/components/schemas/AvatarStatus' voice: anyOf: - type: string - type: 'null' description: Preferred conversation voice for this avatar, when configured. voice_instructions: anyOf: - type: string - type: 'null' description: >- Voice-style instructions for managed conversations using this avatar. required: - id - name - status - runtime_type - is_demo - created_at title: Avatar type: object ApiErrorEnvelope: additionalProperties: false description: Wire format for every non-2xx public API response. examples: - error: code: transport.unsupported message: transport.type=pipecat is not supported param: transport.type request_id: req_01HXY5K8E7QYG3X8Z6N9R7S0VR type: invalid_request properties: error: $ref: '#/components/schemas/ApiError' required: - error title: ApiErrorEnvelope type: object AvatarStatus: description: |- Lifecycle of a custom avatar. `ready` — usable for sessions. `processing` — being fitted / converted. `failed` — fitting failed; will not be usable without re-upload. enum: - ready - processing - failed title: AvatarStatus type: string ApiError: additionalProperties: false description: Concrete error returned inside `ApiErrorEnvelope.error`. properties: code: description: >- Stable machine-readable subcode (lower_snake_case). SDKs should switch on this, not `message`. type: string message: description: Human-readable summary. Not stable; do not parse. type: string param: anyOf: - type: string - type: 'null' description: Offending request field (dot-path), if applicable. request_id: description: Echo of the `X-Request-Id` response header for support. type: string type: $ref: '#/components/schemas/ErrorType' required: - type - code - message - request_id title: ApiError type: object ErrorType: description: |- Top-level error categories. Maps roughly to HTTP status. `code` (a free-form lower_snake_case string on `ApiError`) is the machine-readable subcode SDKs should switch on; `type` is the broad category. enum: - invalid_request - authentication - permission - not_found - conflict - unprocessable - rate_limit - quota_exceeded - internal - service_unavailable title: ErrorType type: string securitySchemes: ApiKey: bearerFormat: sk_live_* description: >- Live API key minted in the dashboard. Pass as `Authorization: Bearer sk_live_…`. Keys are scoped to a single environment (staging / prod). scheme: bearer type: http ````