> ## Documentation Index > Fetch the complete documentation index at: https://docs.livefaces.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create a voice session > Requires sessions:create. Choose a voice, optional face, prompt, and tools. Use your server; keep the API key out of the browser. ## OpenAPI ````yaml /openapi/public-api.json post /v1/sessions openapi: 3.1.0 info: title: LiveFaces Session API version: 0.1.0 description: >- Customer-facing session launch and lifecycle reference. Send API keys only from trusted server code. servers: - url: https://api.livefaces.ai description: Production security: - BearerAuth: [] tags: - name: Authentication - name: Sessions - name: Workflow runs paths: /v1/sessions: post: tags: - Sessions summary: Create a voice session description: >- Requires sessions:create. Choose a voice, optional face, prompt, and tools. Use your server; keep the API key out of the browser. operationId: createSession parameters: - name: Idempotency-Key in: header required: true description: >- Unique ID for one intended launch. Reuse this key and the identical body when retrying that launch. schema: type: string minLength: 1 maxLength: 200 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SessionCreate' responses: '201': description: Successful response headers: X-Request-ID: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/Session' '401': $ref: '#/components/responses/Error401' '403': $ref: '#/components/responses/Error403' '404': $ref: '#/components/responses/Error404' '409': $ref: '#/components/responses/Error409' '422': $ref: '#/components/responses/Error422' '500': $ref: '#/components/responses/Error500' '503': $ref: '#/components/responses/Error503' components: schemas: SessionCreate: type: object properties: voice_id: type: string description: Voice UUID available to the organization. format: uuid face_id: anyOf: - type: string description: Compatible face UUID; omit or use null for audio only. format: uuid - type: 'null' prompt: anyOf: - type: string minLength: 1 maxLength: 32000 - type: 'null' description: >- Instructions for this conversation. Omit or use null for voice defaults; text must not be blank. greeting: anyOf: - type: string minLength: 1 maxLength: 500 - type: 'null' description: >- Omit for the standard greeting; null disables it. Nonblank custom text is delivered according to the selected voice. mcps: type: array items: $ref: '#/components/schemas/SessionMCP' maxItems: 8 description: >- Connections and tools available for this session. Each connection may appear once. participant_identity: type: string description: Identity for the participant joining the room. default: browser minLength: 1 maxLength: 100 tags: type: array maxItems: 20 items: type: string description: Application labels. metadata: type: object additionalProperties: true description: Application context; exclude secrets. required: - voice_id additionalProperties: false Session: type: object properties: id: type: string description: >- Use this session ID for status, token refresh, end, and transcript requests. format: uuid workflow_run_id: anyOf: - type: string description: Present for a workflow session; identifies its workflow run. format: uuid - type: 'null' status: type: string enum: - created - active - completed - failed - cancelled room_name: type: string description: Room name for the connection. livekit_url: type: string description: LiveKit connection URL returned by the service. format: uri participant_token: type: - string - 'null' description: >- Short-lived participant credential, or null after the session becomes terminal. created_at: type: string format: date-time started_at: type: - string - 'null' format: date-time ended_at: type: - string - 'null' format: date-time required: - id - status - room_name - livekit_url - participant_token - created_at - started_at - ended_at additionalProperties: false SessionMCP: type: object properties: mcp_id: type: string description: Registered MCP connection UUID. format: uuid tools: anyOf: - type: array items: type: string minLength: 1 maxLength: 200 maxItems: 128 uniqueItems: true - type: 'null' description: >- Selected discovered tool names. An empty list selects no tools; omit or use null for all available tools. required: - mcp_id additionalProperties: false ApiError: type: object properties: code: type: string description: Application error code. detail: description: Error description or structured validation details. request_id: type: string description: Request identifier for support. required: - code - detail - request_id additionalProperties: true headers: RequestId: description: Identifier for diagnosing this request. schema: type: string responses: Error401: description: Invalid, expired, or revoked API key. headers: X-Request-ID: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ApiError' Error403: description: Missing required scope or access. headers: X-Request-ID: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ApiError' Error404: description: Resource does not exist or is not accessible with this key. headers: X-Request-ID: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ApiError' Error409: description: Request conflicts with current state or idempotency use. headers: X-Request-ID: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ApiError' Error422: description: Invalid request fields, identifiers, or required headers. headers: X-Request-ID: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ApiError' Error500: description: Unexpected service error. headers: X-Request-ID: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ApiError' Error503: description: Session service is currently unavailable. headers: X-Request-ID: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ApiError' securitySchemes: BearerAuth: type: http scheme: bearer description: Organization API key. Keep it on your server. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.