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

> Connect, read status, refresh credentials, and end a conversation.

These endpoints work with the session `id` returned by either launch endpoint. Use the **same API key that created the session**, with the scope required for each operation.

## Connect and observe

Use `livekit_url` and `participant_token` with your browser's LiveKit client. Authorize access in your application before returning these credentials.

Read session status from your server:

```bash theme={null}
curl "https://api.livefaces.ai/v1/sessions/$SESSION_ID" \
  --header "Authorization: Bearer $LIVEFACES_API_KEY"
```

| Status | Meaning |
| - | - |
| `created` | Session setup has begun. |
| `active` | The session is active. |
| `completed` | The session finished normally. |
| `failed` | The session ended unsuccessfully. |
| `cancelled` | The session was explicitly ended. |

An active session can still be waiting for media or a remote participant. Track connection events in your browser separately from API status.

## Refresh connection credentials

`GET` requires `sessions:read` and returns a fresh participant token while the session is connectable. Terminal sessions return `participant_token: null`. Return refreshed credentials only to the authorized participant.

## End the session

```bash theme={null}
curl --request DELETE "https://api.livefaces.ai/v1/sessions/$SESSION_ID" \
  --header "Authorization: Bearer $LIVEFACES_API_KEY"
```

This requires `sessions:delete` and returns the final session state. Ending an already terminal session is safe. Ending a session retains its historical record.

Disconnecting the browser and ending the API session are separate actions. End the session from your server when your application knows the conversation is finished.

## Read a transcript

```bash theme={null}
curl "https://api.livefaces.ai/v1/sessions/$SESSION_ID/transcript?format=text" \
  --header "Authorization: Bearer $LIVEFACES_API_KEY"
```

This requires `sessions:read`. Omit `format=text` for JSON, which includes `text` and `complete`. Availability follows your organization's recording settings, and the saved transcript may lag the live conversation. `complete: false` means saving is unfinished or did not complete.


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