---
title: Orvyn Public API
description: One stable API for live avatar sessions — create a session, connect the stream, end it. REST control plane, WebSocket media, generated OpenAPI reference.
sidebar:
  label: Overview
  order: 0
---

The Orvyn Public API is a small, stable REST control plane plus a WebSocket media
stream. Create and start a live avatar session in **one call**, hand a short-lived
token to your frontend, stream the avatar over WebSocket, and end the session from
your backend when done.

<div class="steps-preview">

**You will have a live avatar session in one API call.**

</div>

<CardGroup cols={2}>
  <Card title="Quickstart" href="/quickstart" icon="rocket">
    Zero to a live session in five minutes — copy-pasteable.
  </Card>
  <Card title="API reference" href="/reference" icon="file-code">
    The generated OpenAPI 3.1 reference — six endpoints, authoritative.
  </Card>
  <Card title="Authentication" href="/guides/authentication" icon="lock">
    API keys, auth headers, and short-lived WebSocket tokens.
  </Card>
  <Card title="Session lifecycle" href="/guides/session-lifecycle" icon="refresh">
    States, ownership, and cleanup semantics.
  </Card>
</CardGroup>

## How the platform fits together

You interact with three things:

- **The REST control plane** — six `/v1/` endpoints for session and API-key
  management. Always authenticated with your API key.
- **The media WebSocket** — a browser-facing stream that carries fMP4 video and
  SDK control messages. Authenticated with a short-lived token embedded in the
  connection URL.
- **Your backend** — the owner of every credential. It mints provider tokens,
  creates sessions, and ends them.

The rendering backend, media adapters, and provider internals are swappable
implementation details. Public responses expose product concepts only — no
internal endpoint names, container ids, or provider infrastructure ever appear.

## The six canonical endpoints

The V0 contract is **exactly these six paths** — no others:

| Method | Path | Purpose |
|---|---|---|
| `POST` | `/v1/sessions` | Create AND start a session in one call |
| `GET` | `/v1/sessions/{session_id}` | Get session status and timings |
| `POST` | `/v1/sessions/{session_id}/end` | End a session and release resources |
| `POST` | `/v1/sessions/{session_id}/client-token` | Mint a fresh short-lived client token |
| `POST` | `/v1/api-keys` | Create an API key (admin surface) |
| `DELETE` | `/v1/api-keys/{key_id}` | Revoke an API key (admin surface) |

Every path, schema, and error code on this site is generated from the OpenAPI 3.1
specification — the [API reference](/reference) is authoritative. Narrative pages
explain behavior; they never redefine the contract.

## Where to start

1. [Get a live session in five minutes](/quickstart) — the 60-second version.
2. [Wire up authentication](/guides/authentication) — API keys + token lifecycle.
3. [Understand the session lifecycle](/guides/session-lifecycle) — states and
   cleanup.
4. Browse the [full API reference](/reference).