> ## 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

> Choose a voice and optional face, instructions, and integration tools.

Call `POST /v1/sessions` from your server with a key that has `sessions:create`. Supply a fresh **Idempotency-Key** for each intended conversation; reuse it and the same body for retries.

```bash theme={null}
curl --request POST 'https://api.livefaces.ai/v1/sessions' \
  --header "Authorization: Bearer $LIVEFACES_API_KEY" \
  --header 'Content-Type: application/json' \
  --header "Idempotency-Key: $SESSION_ATTEMPT_ID" \
  --data '{
    "voice_id": "11111111-1111-4111-8111-111111111111",
    "participant_identity": "customer-123",
    "prompt": "Help the customer describe their order issue. Ask for the order number."
  }'
```

Set the environment variables on your server and replace the example voice UUID with one available to your organization. Keep the attempt ID stable if you retry.

| Field | Use |
| - | - |
| `voice_id` | Required voice UUID. |
| `face_id` | Optional compatible face UUID; omit or use `null` for audio only. |
| `prompt` | Optional instructions, up to 32,000 characters. Omit or use `null` for the voice's defaults. |
| `greeting` | Omit for the standard greeting; `null` disables it. Custom text is limited to 500 characters; delivery depends on the selected voice. |
| `participant_identity` | Participant identifier, 1–100 characters; defaults to `browser`. |
| `mcps` | Optional selection of up to eight MCP connections and their tools. |
| `tags`, `metadata` | Optional application labels and context. Do not include secrets. |

## Optional tool selection

Add this to the request body to select a registered connection and named tools:

```json theme={null}
{
  "mcps": [
    {
      "mcp_id": "22222222-2222-4222-8222-222222222222",
      "tools": ["lookup_order"]
    }
  ]
}
```

Use your actual connection UUID and discovered tool names. Select only the tools the conversation needs. The fragment above extends the request; `voice_id` is still required.

## Response

A successful request returns `201` and a session containing:

```json theme={null}
{
  "id": "33333333-3333-4333-8333-333333333333",
  "status": "active",
  "room_name": "example-room",
  "livekit_url": "wss://YOUR_LIVEKIT_HOST",
  "participant_token": "SHORT_LIVED_PARTICIPANT_TOKEN",
  "created_at": "2026-01-01T12:00:00Z",
  "started_at": "2026-01-01T12:00:01Z",
  "ended_at": null,
  "workflow_run_id": null
}
```

This is an illustrative response; use the returned URL and token. Check that a token is present before connecting. Save `id` for [status checks, token refresh, and ending the session](https://docs.livefaces.ai/api/session-lifecycle.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.