Mascotte API

Put a talking video avatar (a "mascotte") inside your own website or app. Your server starts a session with an API key; your page shows the session in a frame; the visitor talks to the mascotte by voice or by typing. The mascotte answers from its own role and knowledge, with its own face and voice. You can also bring your own language model or voice, and an AI assistant can use the same key through MCP (Model Context Protocol).

This file is written for people and for AI coding agents. Everything needed to integrate is here or linked from here.

1. How it fits together

  1. A person makes a mascotte in the Mascotte app (https://app.mascotte.ai) and saves it. Only video mascottes can be embedded. Its role, knowledge documents, greeting, language and voice are set in the app.
  2. The person makes an API key on the Developers page and stores it on their own server.
  3. Your SERVER calls POST /api/v1/sessions with the key and gets a session url. The key never reaches a browser.
  4. Your PAGE shows that url with the embed script (or a plain iframe). The visitor presses Start and talks.
  5. Your page hears every line said (events) and can make the mascotte ask or say things (commands).
  6. The session ends when the visitor hangs up, when your server ends it, or when its minutes are up.

2. Getting a key

3. Base URL and authentication

Base URL: https://app.mascotte.ai

Every /api/v1 request carries the key:

Authorization: Bearer mk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Rules:

4. Errors

Every error is an HTTP status of 400 or more with a JSON body:

{ "error": "a sentence for a person", "code": "machine_readable_reason", "reason": "machine_readable_reason" }

Switch on the HTTP status and code. Some errors (a malformed field, an unknown route) carry only error: use the status. The wording of error can change; code does not.

HTTPcodemeaningwhat to do
400browserthe request carried an Origin headercall from your server
401keykey missing, mistyped or revokedstop; fix the key
400origin_requiredthe key lists several websites and no origin was sentsend origin
403origin_not_allowedorigin is not one of the key's websitesadd the site to the key
403key_pausedMascotte paused this keystop; contact Mascotte
429rate_limittoo many sessions started this minute, or over 600 requests an hourwait 60 s; at most 2 retries
429concurrency_limitthe key already has its maximum of conversations goingend one, or retry in a minute
429daily_limitthe key used its minutes for today (UTC)wait until 00:00 UTC
404(none)no such mascotte, session or routecheck the id (GET /api/v1/mascottes)
409not_videothe mascotte is a 3D or MetaHuman one, which cannot be embeddedpick a video mascotte
409(none)the mascotte's share link is switched off in the appswitch it on in the app
400(none)a field is wrong; error names itfix the request

5. Routes

GET /api/v1/mascottes

The key owner's video mascottes, newest first.

{ "mascottes": [ { "id": 123, "name": "Erasmus", "base": "gnm", "updated": "2026-11-20T09:12:00.000Z" } ] }

id stays the same when the mascotte is renamed. Send it (or the exact name) as mascotte below.

POST /api/v1/sessions

Starts a conversation. Answers 201:

{
  "id": "ses_42",
  "url": "https://app.mascotte.ai/web/embed_frame.html?s=AbCdEfGhIjKlMnOpQrStUv&view=face",
  "mascotte": { "id": 123, "name": "Erasmus" },
  "expiresAt": "2026-11-20T14:30:00.000Z",
  "origin": "https://your-site.example",
  "mode": "full",
  "minutes": 30
}

Body fields (only mascotte is required):

fieldtypemeaning
mascottenumber or stringIts id, or its exact name.
originstringThe page that shows it, like https://your-site.example (https, or http on localhost). Send it: without it the frame sends no events and takes no commands.
instructionsstringUp to 64,000 characters for this conversation only (a visitor's name, a case file, rules).
instructionsModestring"append" (default: added after the mascotte's own role) or "replace" (used instead of it).
greetingstringIts first line, up to 600 characters.
languagestringA code like "en", "nl", "fr" or "zh".
viewstring"face" (the face and a call bar; your page draws the conversation) or "full" (with a chat panel, the default).
minutesinteger1 to 120, default 30. Never more than what is left of the key's minutes today.
resolutionstring"normal" (512 px, default) or "hd" (640 px, sharper and slower).
renderQualitystring"best" or "fast" (about twice as quick, a little softer).
framingstring"as-is" (the whole picture) or "auto" (zooms in on the face).
movementStyleinteger0 to 2147483647: a different way of moving the head.
restingLoopinteger1 to 6: how long the face rests between answers, about 1.3 s a step.
interruptbooleantrue lets the visitor talk over the mascotte. Default false.
micSensitivitystring"low", "normal" or "high".
replyLengthstring"short", "medium" or "long".
modestring"full" (our language model and voice, the default) or "own_ai" (yours, section 7).
llmProviderstringThe id of your own language model, like "prv_12" (section 7).
voiceProviderstringThe id of your own voice, like "prv_13" (section 7).
voiceEndpointstringAn https address of your own voice service, given per session (section 7). Not with voiceProvider.
voiceSecretstring16 to 256 characters, sent to voiceEndpoint as a Bearer token.

Example:

curl -X POST https://app.mascotte.ai/api/v1/sessions \
  -H "Authorization: Bearer $MASCOTTE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mascotte": 123,
    "origin": "https://your-site.example",
    "language": "en",
    "greeting": "Welcome! Shall we begin?",
    "instructions": "Ask the intake questions one at a time.",
    "view": "face",
    "minutes": 30
  }'

GET /api/v1/sessions/{id}

{ "id": "ses_42", "state": "open", "created": "...", "opened": "...", "ended": null,
  "expiresAt": "...", "minutes": 3, "mode": "full" }

state is "waiting" (made, not opened yet), "open", "ended" or "expired". minutes counts started minutes from the frame opening to the hang-up.

DELETE /api/v1/sessions/{id}

Ends it now; answers the same shape with "state": "ended". End it from your server for a visitor who never hangs up.

GET /api/v1/usage

This key today and this month, against its limits:

{ "key": { "name": "Website" },
  "today": { "minutes": 14, "sessions": 3, "atOnce": 1 },
  "month": { "minutes": 210, "sessions": 41 },
  "limits": { "maxConcurrent": 2, "maxDailyMinutes": 120, "createPerMinute": 10, "origins": [] },
  "paused": false, "free": true }

6. Showing it in your page

With the embed script:

<div id="avatar" style="height:600px"></div>
<script src="https://app.mascotte.ai/web/embed.js"></script>
<script>
  // sessionUrl came from YOUR server (POST /api/v1/sessions). Never put the key here.
  const m = Mascotte.mount("#avatar", { url: sessionUrl });
  m.on("message", (e) => console.log(e.role, e.text));   // "user" or "avatar"
  m.on("started", () => m.say("Shall we start with your date of birth?"));
  m.on("ended", () => console.log("the visitor hung up"));
</script>

Mascotte.mount(target, options): target is a CSS selector or an element. Options: url (required), title, radius (corner radius in px, default 16), background (CSS colour), onEvent (gets every event).

Events (m.on(type, fn); "*" gets them all; each is an object with type):

Commands (after "started"):

Without the script: put the url in an iframe with allow="microphone; camera; autoplay; fullscreen". The frame posts { source: "mascotte", type, ... } messages to the origin you gave, and takes { source: "mascotte-host", type: "send" | "say" | "end", text } from that page only. Check event.origin is https://app.mascotte.ai.

7. Your own language model and voice

Bring your own language model, your own voice, or both; Mascotte provides the face and the video. A person stores them once on the Developers page under "Using your own AI and voice"; each gets an id like prv_12. Endpoints and keys are stored encrypted, shown only by their last four characters, and never sent to a browser. A session names them:

{ "mascotte": 123, "origin": "https://your-site.example",
  "mode": "own_ai", "llmProvider": "prv_12", "voiceProvider": "prv_13" }

Language model: any OpenAI-compatible chat completions address (OpenAI, Azure, Mistral, Groq, OpenRouter, your own). Mascotte POSTs { model, messages, max_tokens, temperature } with your key as a Bearer token and reads choices[0].message.content. The first message is the mascotte's instructions. A reply may start with an emotion tag like [happy]; it drives the face and is never spoken. It must answer within 20 seconds and send under 1 MB.

Voice: for each sentence Mascotte POSTs { text, language, session, mascotte } with your key (or the session's voiceSecret) as a Bearer token. Answer 200 with audio/mpeg or audio/wav, within 10 seconds, under 2 MB. The address must be https on the public internet.

When either fails the mascotte ends that reply with a short apology and your page gets an "error" event with reason "llm" or "voice".

8. MCP: use Mascotte from an AI assistant

Address: https://app.mascotte.ai/api/v1/mcp. Streamable HTTP, JSON responses (no event stream), stateless, POST only. Authorization is the same API key: Authorization: Bearer mk_live_... The same limits and logging apply.

Claude Code:

claude mcp add --transport http mascotte https://app.mascotte.ai/api/v1/mcp --header "Authorization: Bearer $MASCOTTE_KEY"

Cursor (.cursor/mcp.json):

{ "mcpServers": { "mascotte": { "url": "https://app.mascotte.ai/api/v1/mcp",
                                "headers": { "Authorization": "Bearer mk_live_..." } } } }

Claude Desktop (claude_desktop_config.json):

{ "mcpServers": { "mascotte": { "command": "npx",
    "args": ["-y", "mcp-remote", "https://app.mascotte.ai/api/v1/mcp", "--header", "Authorization:${MASCOTTE_AUTH}"],
    "env": { "MASCOTTE_AUTH": "Bearer mk_live_..." } } } }

Tools:

There are no delete tools. character is the number from list_characters or the exact name.

9. Limits during the beta

Per key (Mascotte can raise them per key; ask):

The API is free during the beta.

10. Privacy

11. A complete minimal example (Node 18+, no packages)

server.mjs, run with MASCOTTE_KEY in the environment:

import http from "node:http";
const KEY = process.env.MASCOTTE_KEY;
http.createServer(async (req, res) => {
  if (req.url === "/session") {
    const r = await fetch("https://app.mascotte.ai/api/v1/sessions", {
      method: "POST",
      headers: { "Authorization": "Bearer " + KEY, "Content-Type": "application/json" },
      body: JSON.stringify({ mascotte: 123, origin: "http://localhost:8080", view: "face" }),
    });
    res.writeHead(r.status, { "Content-Type": "application/json" });
    return res.end(await r.text());
  }
  res.writeHead(200, { "Content-Type": "text/html" });
  res.end(`<div id="avatar" style="height:600px"></div>
<script src="https://app.mascotte.ai/web/embed.js"></script>
<script>
  fetch("/session").then(r => r.json()).then(s => {
    const m = Mascotte.mount("#avatar", { url: s.url });
    m.on("message", e => console.log(e.role + ": " + e.text));
  });
</script>`);
}).listen(8080);

Open http://localhost:8080 and press Start. In production, sign your own visitors in before /session hands out a conversation, so nobody can spend the key's minutes.