> ## Documentation Index > Fetch the complete documentation index at: https://docs.yourproducthere.ai/llms.txt > Use this file to discover all available pages before exploring further. # List actors ## OpenAPI ````yaml /openapi.yaml get /actors openapi: 3.1.0 info: title: YPH Public API version: 1.0.0 description: | Programmatic access to Digital Samples, Actors, Insta Swaps, and webhooks. Authenticate with `Authorization: Bearer yph_sk_live_…`. servers: - url: https://api.yourproducthere.ai/v1 description: Production security: - bearerAuth: [] tags: - name: System - name: Account - name: Actors - name: Digital Samples - name: Insta Swaps - name: Webhooks paths: /actors: get: tags: - Actors summary: List actors parameters: - $ref: '#/components/parameters/AccountTokenQuery' responses: '200': description: Actor list content: application/json: schema: type: object properties: actors: type: array items: $ref: '#/components/schemas/Actor' '401': $ref: '#/components/responses/Unauthorized' components: parameters: AccountTokenQuery: name: accountToken in: query required: false schema: type: string maxLength: 128 description: > Filter results to resources whose `accountToken` equals this opaque integrator id. On digital samples this is the **brand** token; on actors and insta-swaps it is the **creator** (or brand in self-service mode). Embed widgets should always pass this — without it, UIs show no rows. schemas: Actor: type: object description: > Actor resource returned by GET, POST, and PATCH. - **Write-only (POST/PATCH body):** `faceAssetUrl`, `bodyAssetUrl`, `voiceClipUrl` — your public HTTPS source URLs. YPH ingests copies into private storage. - **Read-only (responses):** `signedFaceAssetUrl`, `signedBodyAssetUrl`, `signedVoiceClipUrl` — short-lived presigned GET URLs for preview/download. Never send these back on PATCH. - **Echo (responses):** `faceAssetUrl`, `bodyAssetUrl`, `voiceClipUrl` repeat the external source URLs you submitted (null if the actor was created via the YPH app upload flow). - **Integrator identity:** `accountToken` identifies the **creator** (or the brand when producing in-house). See [Integrator tokens](/guides/integrator-tokens). properties: id: type: string format: uuid displayName: type: string maxLength: 80 accountToken: type: string nullable: true maxLength: 128 description: Integrator creator or brand actor id. faceAssetUrl: type: string format: uri nullable: true readOnly: true description: >- Echo of your external face image HTTPS URL (write via POST/PATCH body only). Null when no external source was registered. bodyAssetUrl: type: string format: uri nullable: true readOnly: true description: >- Echo of your external body image HTTPS URL (write via POST/PATCH body only). voiceClipUrl: type: string format: uri nullable: true readOnly: true description: >- Echo of your external voice clip HTTPS URL (write via POST/PATCH body only). signedFaceAssetUrl: type: string format: uri nullable: true readOnly: true description: >- Short-lived presigned GET URL for the ingested face asset (typically valid ~10 minutes). signedBodyAssetUrl: type: string format: uri nullable: true readOnly: true description: Short-lived presigned GET URL for the ingested body asset. signedVoiceClipUrl: type: string format: uri nullable: true readOnly: true description: Short-lived presigned GET URL for the ingested voice clip. identityPrepStatus: type: string readOnly: true enum: - pending - preparing - ready - failed description: >- Whether the actor has completed first-render AI identity prep (automatic photo optimization). `pending` until the first paid render prepares the assets, then `preparing` → `ready`. `failed` is non-blocking — renders still succeed with defaults. Poll this field after a PATCH that changes `faceAssetUrl`/`bodyAssetUrl` (which resets it to `pending`). identityPrepReadyAt: type: string format: date-time nullable: true readOnly: true description: >- Timestamp when identity prep last succeeded, or null if never prepared. warnings: type: array readOnly: true items: type: string description: >- Non-blocking quality hints from asset validation (e.g. recommended dimensions or audio duration). createdAt: type: string format: date-time updatedAt: type: string format: date-time example: id: a1c02874-e339-4d11-8fa1-e6a2bc38c41d displayName: Corporate Professional accountToken: creator_42 faceAssetUrl: https://cdn.example.com/actors/face.jpg bodyAssetUrl: https://cdn.example.com/actors/body.jpg voiceClipUrl: https://cdn.example.com/actors/voice.mp3 signedFaceAssetUrl: >- https://account.r2.cloudflarestorage.com/bucket/identity-assets/face.png?X-Amz-Signature=... signedBodyAssetUrl: >- https://account.r2.cloudflarestorage.com/bucket/identity-assets/body.png?X-Amz-Signature=... signedVoiceClipUrl: >- https://account.r2.cloudflarestorage.com/bucket/identity-assets/voice.mp3?X-Amz-Signature=... identityPrepStatus: pending identityPrepReadyAt: null warnings: - 'faceAssetUrl: image dimensions below recommended 480x832' createdAt: '2026-06-20T12:00:00Z' updatedAt: '2026-06-20T12:05:00Z' Error: type: object properties: code: type: string description: >- A machine-readable, uppercase error code (e.g. `REQUIRED_FIELD_MISSING`, `INVALID_PARAMETER`, `RESOURCE_NOT_FOUND`, `UNAUTHORIZED`, `CONFLICT`). error: type: string description: A human-readable error message explaining why the request failed. parameter: type: string nullable: true description: >- The name of the specific input parameter or body field that caused the error (e.g. `seedVideoUrl`, `title`, etc.). details: type: object nullable: true description: >- Additional key-value pairs providing context or structured details about the failure. example: code: REQUIRED_FIELD_MISSING error: title is required parameter: title details: null responses: Unauthorized: description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/Error' examples: unauthorized: summary: Invalid API Key value: code: UNAUTHORIZED error: Unauthorized securitySchemes: bearerAuth: type: http scheme: bearer description: Your organization API key starting with yph_sk_live_… ````