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

# Session API

> Launch a voice conversation or a published workflow from your application.

Send requests from your server to `https://api.livefaces.ai` with:

```http theme={null}
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

Use the canonical API origin directly; older `.lagena.ai` application URLs redirect.

## Choose a starting point

| Experience | Request | Required scope |
| - | - | - |
| Voice with optional face, prompt, and tools | `POST /v1/sessions` | `sessions:create` |
| Published workflow with initial inputs | `POST /v1/workflow-runs` | `workflows:run` |
| Read either session / refresh its token | `GET /v1/sessions/{session_id}` | `sessions:read` |
| End either session | `DELETE /v1/sessions/{session_id}` | `sessions:delete` |
| Read its saved transcript | `GET /v1/sessions/{session_id}/transcript` | `sessions:read` |
| Check the API key's organization and scopes | `GET /v1/auth/api-key` | Valid API key |

Use catalog and published-revision UUIDs provisioned for your organization. Display names and workflow version numbers cannot replace these IDs.

## Connection flow

```mermaid theme={null}
sequenceDiagram
  participant Browser
  participant Server as Your server
  participant API as Session API
  Browser->>Server: Request a conversation
  Server->>API: Create session with API key
  API-->>Server: Session ID, room URL, participant token
  Server-->>Browser: Authorized connection details
  Browser->>Browser: Connect with LiveKit client
```

The response contains `id`, `livekit_url`, and `participant_token`. Use the URL and token with a LiveKit client to join the session. A session created without a face has no digital-human video.

Keep the API key on your server. Return connection details only to the participant authorized to join; participant tokens are credentials too. Session creation depends on the services enabled for your organization. A `503` means creation is currently unavailable; see [errors and retries](https://docs.livefaces.ai/api/errors.md).

Begin with [API keys](https://docs.livefaces.ai/security/api-keys.md), then [create a voice session](https://docs.livefaces.ai/api/start-session.md) or [start a workflow](https://docs.livefaces.ai/api/start-workflow.md).


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