Quickstart

atmee keys create --name "quickstart" --avatar <avatar-id> --spend-cap 50 --out .env

curl https://api.atmanity.us/v1/avatars \
  -H "X-Api-Key: $ATMEE_API_KEY"

curl -X POST https://api.atmanity.us/v1/sessions \
  -H "X-Api-Key: $ATMEE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "avatarId": "<avatar-id>", "maxDurationSeconds": 300 }'

{
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "serverUrl": "wss://atmanity.livekit.cloud",
  "roomName": "rk-8f14e45f-ceea-467a-9f21-4c2f5b3a91cd",
  "userToken": "eyJhbGciOi…",
  "actualDurationSeconds": 300,
  "requestedDurationSeconds": 300,
  "durationCapped": false,
  "billingMode": "reserve"
}

// server.mjs: the only place the key exists. Node 20.6+, no packages.
import { readFile } from "node:fs/promises";
import http from "node:http";

const API = "https://api.atmanity.us";
const { ATMEE_API_KEY, AVATAR_ID } = process.env;
const mine = new Set(); // sessions this server started

// Most errors are JSON with an `error` code, but a wrong key or an avatar the
// key may not use answers 401 or 403 as plain text or with no body.
async function read(r) {
  const text = await r.text();
  try {
    return text ? JSON.parse(text) : {};
  } catch {
    return { message: text };
  }
}
const errorCode = (r, body) =>
  typeof body.error === "string" ? body.error : `http_${r.status}`;

function atmee(method, path, body) {
  return fetch(API + path, {
    method,
    headers: { "X-Api-Key": ATMEE_API_KEY, "Content-Type": "application/json" },
    body: body && JSON.stringify(body),
  });
}

http
  .createServer(async (req, res) => {
    const json = (status, data) =>
      res
        .writeHead(status, { "Content-Type": "application/json" })
        .end(JSON.stringify(data));

    if (req.method === "GET" && req.url === "/") {
      res.writeHead(200, { "Content-Type": "text/html" });
      return res.end(await readFile("index.html"));
    }

    // Start. Every call is a billed session: in a real app, put this behind your sign-in.
    if (req.method === "POST" && req.url === "/api/session") {
      const r = await atmee("POST", "/v1/sessions", {
        avatarId: AVATAR_ID,
        maxDurationSeconds: 600,
      });
      const body = await read(r);
      if (!r.ok) {
        console.warn(
          "start failed",
          r.status,
          errorCode(r, body),
          body.message,
        );
        return json(r.status, { error: errorCode(r, body) }); // the code only, never the details
      }
      mine.add(body.sessionId);
      // Forward only what the page needs to join and to end. Never the key.
      const { sessionId, serverUrl, userToken } = body;
      return json(200, { sessionId, serverUrl, userToken });
    }

    // End: POST /api/session/<id>/end. Safe to call twice.
    const m = req.url.match(/^\/api\/session\/([0-9a-f-]{36})\/end$/);
    if (req.method === "POST" && m && mine.has(m[1])) {
      const r = await atmee("POST", `/v1/sessions/${m[1]}/end`);
      if (r.ok) mine.delete(m[1]);
      return json(r.status, await read(r));
    }

    res.writeHead(404).end();
  })
  .listen(3000, () => console.log("http://localhost:3000"));

<video id="avatar" autoplay playsinline width="512" height="512"></video>
<audio id="voice" autoplay></audio>
<button id="start">Talk to the avatar</button>
<button id="stop" hidden>End</button>
<p id="status"></p>

<script type="module">
  import {
    Room,
    RoomEvent,
    Track,
  } from "https://cdn.jsdelivr.net/npm/livekit-client@2.22.3/+esm";

  const $ = (id) => document.getElementById(id);
  let room, endUrl;

  function end() {
    if (!endUrl) return;
    navigator.sendBeacon(endUrl); // your server ends the session, even while the page closes
    endUrl = null;
    room?.disconnect();
    $("stop").hidden = true;
    $("start").hidden = false;
    $("status").textContent = "Ended.";
  }

  $("start").onclick = async () => {
    $("start").hidden = true;
    $("status").textContent = "Connecting…"; // the start takes 15 to 20 seconds
    const res = await fetch("/api/session", { method: "POST" });
    const s = await res.json();
    if (!res.ok) {
      $("status").textContent = `Couldn't start (${s.error}).`;
      $("start").hidden = false;
      return;
    }
    endUrl = `/api/session/${s.sessionId}/end`;
    room = new Room();
    room.on(RoomEvent.TrackSubscribed, (track) => {
      // The avatar publishes one video and one audio track.
      track.attach($(track.kind === Track.Kind.Video ? "avatar" : "voice"));
    });
    room.on(RoomEvent.Disconnected, end);
    await room.connect(s.serverUrl, s.userToken); // join within 60 seconds
    await room.startAudio();
    await room.localParticipant.setMicrophoneEnabled(true);
    $("status").textContent = "Say hello.";
    $("stop").hidden = false;
  };

  $("stop").onclick = end;
  addEventListener("pagehide", end);
</script>

node --env-file=.env server.mjs

curl -X POST https://api.atmanity.us/v1/sessions/550e8400-e29b-41d4-a716-446655440000/end \
  -H "X-Api-Key: $ATMEE_API_KEY"

{
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "endedAt": "2026-11-04T16:42:10Z",
  "alreadyEnded": false,
  "endReason": "ended_by_api"
}