> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tavus.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Server

> Server-side helpers for managing Tavus conversation lifecycle without leaking your API key to the browser.

# Server

These primitives are not React components — they are server route handlers and small browser-side fetch helpers. Use them to create and end Tavus conversations without bundling your `TAVUS_API_KEY` into client JS.

| Add command                                       | Use for                                                                                                | Generated files                                                                           | Browser exports                                                | Server exports / route                                    | Notes                                                                                                 |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------- | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `npx @tavus/cvi-ui@latest add tavus-api`          | Next.js App Router, Next.js Pages Router, Remix, TanStack Start                                        | Framework route plus `<components-path>/lib/tavus-client.ts`                              | `createTavusConversation(params?)`, `endTavusConversation(id)` | `POST /api/tavus` route for create/end actions            | CLI exits on unsupported client-only frameworks instead of creating an unsafe browser API-key client. |
| `npx @tavus/cvi-ui@latest add tavus-api-vite-ssr` | Vite projects with a server runtime such as Vinxi, Hono, vike-server, Express, Bun, Cloudflare Workers | `<components-path>/lib/tavus-api-vite-ssr.ts` and `<components-path>/lib/tavus-client.ts` | `createTavusConversation(params?)`, `endTavusConversation(id)` | `handleTavusRequest(request: Request): Promise<Response>` | You mount the handler at `POST /api/tavus`; plain client-only Vite remains unsupported.               |

<Warning>
  Keep `TAVUS_API_KEY` only in server environment variables. Do not prefix it with client-exposed environment names such as `VITE_` or `NEXT_PUBLIC_`.
</Warning>

### Tavus API

The `tavus-api` module installs a framework-specific server route that creates and ends Tavus conversations on your backend, plus a small browser client that calls that route.

```bash theme={null}
npx @tavus/cvi-ui@latest add tavus-api
```

<Tabs>
  <Tab title="Description">
    The `tavus-api` module installs a server route that creates and ends Tavus conversations on your backend, plus a small browser client that calls that route. Your `TAVUS_API_KEY` stays on the server and is never bundled into your client JS.

    **What gets installed**

    The CLI detects your framework and installs the matching server route:

    | Framework              | Server route file         |
    | ---------------------- | ------------------------- |
    | Next.js (App Router)   | `app/api/tavus/route.ts`  |
    | Next.js (Pages Router) | `pages/api/tavus.ts`      |
    | Remix                  | `app/routes/api.tavus.ts` |
    | TanStack Start         | `app/routes/api/tavus.ts` |

    Plus the browser-side client at `<components-path>/lib/tavus-client.ts`, which exports `createTavusConversation(params?)` and `endTavusConversation(id)`. Both functions `POST` to `/api/tavus`; the route forwards `params` verbatim to the Tavus REST API, so every field on [`POST /v2/conversations`](/api-reference/conversations/create-conversation) works. New Tavus fields work without a CLI update.

    **Behaviour for unsupported frameworks**

    If the CLI doesn't recognise the framework as one with a built-in server (plain Vite, Expo, manual setups), `add tavus-api` exits with an error rather than silently installing a key-exposing client. See the Vite-with-server opt-in below.

    **Required environment variable (server only — never on the client)**

    * `TAVUS_API_KEY` — required. [Create one in the Tavus Developer Portal.](https://platform.tavus.io/api-keys)
  </Tab>

  <Tab title="Code">
    ```tsx theme={null}
    import { createTavusConversation, endTavusConversation } from './lib/tavus-client';
    ```

    ```tsx theme={null}
    const handleStart = async () => {
      const { conversation_id, conversation_url } = await createTavusConversation({
        persona_id: 'pcb7a34da5fe',
        "properties": {
          "language": "english"
        }
      });
      // ...join the call with conversation_url
    };

    const handleEnd = async (id: string) => {
      await endTavusConversation(id);
    };
    ```
  </Tab>
</Tabs>

### Tavus API for Vite (with a server runtime)

For Vite projects that have a server (Vinxi, Hono, vike-server, custom Express, Bun, Cloudflare Workers, …), `add tavus-api-vite-ssr` installs a runtime-agnostic Request handler you wire into your middleware.

```bash theme={null}
npx @tavus/cvi-ui@latest add tavus-api-vite-ssr
```

<Tabs>
  <Tab title="Description">
    Installs `<components-path>/lib/tavus-api-vite-ssr.ts` exporting `handleTavusRequest(request: Request): Promise<Response>`, plus the matching `lib/tavus-client.ts`. The handler uses the standard Web Fetch `Request`/`Response` interfaces, so it plugs into any server runtime that speaks fetch.

    **Wiring examples** (the file header includes these too):

    * **Hono**:
      ```ts theme={null}
      import { handleTavusRequest } from './lib/tavus-api-vite-ssr';
      app.post('/api/tavus', (c) => handleTavusRequest(c.req.raw));
      ```
    * **h3 / Vinxi**:
      ```ts theme={null}
      import { eventHandler, toWebRequest } from 'h3';
      import { handleTavusRequest } from './lib/tavus-api-vite-ssr';
      export default eventHandler((event) => handleTavusRequest(toWebRequest(event)));
      ```
    * **Express** (with a Web Fetch adapter such as `@hattip/adapter-node`):
      ```ts theme={null}
      app.post('/api/tavus', async (req, res) => {
        const webRes = await handleTavusRequest(toWebRequest(req));
        // pipe webRes back to res
      });
      ```

    Once the handler is mounted at `POST /api/tavus`, the installed `lib/tavus-client.ts` calls it from the browser — no API key on the client.

    **Required environment variable (server only)** — `TAVUS_API_KEY`. [Create one in the Tavus Developer Portal.](https://platform.tavus.io/api-keys)

    The full create-conversation field surface is supported via `createTavusConversation(params)` — see the [API reference](/api-reference/conversations/create-conversation) and the `tavus-api` section above for the params shape.
  </Tab>

  <Tab title="Code">
    ```tsx theme={null}
    import { handleTavusRequest } from './lib/tavus-api-vite-ssr';
    // …mount via your server's middleware (Hono, h3, Express, Cloudflare, Bun, …)

    import { createTavusConversation } from './lib/tavus-client';
    const { conversation_id, conversation_url } = await createTavusConversation({
      persona_id: 'pcb7a34da5fe',
      "properties": {
        "language": "english"
      }
    });
    ```
  </Tab>
</Tabs>

<Note>
  **No client-only mode.** We deliberately do not ship a browser-direct client. Calling Tavus directly from the browser would put your API key in the bundle, which is unsafe in any deployed context. If your project has no server, add one (Vinxi, Hono, vike-server, …) and use `tavus-api-vite-ssr` above.
</Note>