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.
- This file: https://app.mascotte.ai/llms.txt (also /llms-full.txt, the same text)
- The same reference as a web page: https://app.mascotte.ai/docs/api
- OpenAPI 3 description: https://app.mascotte.ai/openapi.json
- Embed script: https://app.mascotte.ai/web/embed.js
- MCP server: https://app.mascotte.ai/api/v1/mcp
- Keys: https://app.mascotte.ai/web/developers.html (a person signs in; an agent cannot make a key)
1. How it fits together
- 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.
- The person makes an API key on the Developers page and stores it on their own server.
- Your SERVER calls POST /api/v1/sessions with the key and gets a session
url. The key never reaches a browser. - Your PAGE shows that
urlwith the embed script (or a plain iframe). The visitor presses Start and talks. - Your page hears every line said (events) and can make the mascotte ask or say things (commands).
- The session ends when the visitor hangs up, when your server ends it, or when its minutes are up.
2. Getting a key
- Sign in at https://app.mascotte.ai, open Developers (https://app.mascotte.ai/web/developers.html), tick the beta terms and press Create key. An AI agent cannot do this for you: ask the person.
- A key looks like mk_live_ followed by 32 letters, digits, "-" or "_". It is shown ONCE. Lost: revoke it and make another. Up to 20 keys per account.
- A key may list the websites allowed to show its sessions (for example https://your-site.example). With a list, a session for any other site is refused.
- Revoking a key stops it at once and ends all of its open sessions.
3. Base URL and authentication
Base URL: https://app.mascotte.ai
Every /api/v1 request carries the key:
Authorization: Bearer mk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Rules:
- Call the API from your server, never from a web page. A request with an Origin header (every browser sends one) is refused with 400, code "browser". curl, Node, Python, PHP and other servers send no Origin, so they work.
- Never put the key in a page, in source code, in a commit, on a command line or in a URL. Read it from an environment variable or a secrets store. A key a browser can read is a public key.
- Request bodies are JSON with Content-Type: application/json. Responses are JSON (UTF-8).
- The session
urlis safe to give to a browser: it opens one conversation and stops working when it ends.
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.
| HTTP | code | meaning | what to do |
|---|---|---|---|
| 400 | browser | the request carried an Origin header | call from your server |
| 401 | key | key missing, mistyped or revoked | stop; fix the key |
| 400 | origin_required | the key lists several websites and no origin was sent | send origin |
| 403 | origin_not_allowed | origin is not one of the key's websites | add the site to the key |
| 403 | key_paused | Mascotte paused this key | stop; contact Mascotte |
| 429 | rate_limit | too many sessions started this minute, or over 600 requests an hour | wait 60 s; at most 2 retries |
| 429 | concurrency_limit | the key already has its maximum of conversations going | end one, or retry in a minute |
| 429 | daily_limit | the key used its minutes for today (UTC) | wait until 00:00 UTC |
| 404 | (none) | no such mascotte, session or route | check the id (GET /api/v1/mascottes) |
| 409 | not_video | the mascotte is a 3D or MetaHuman one, which cannot be embedded | pick a video mascotte |
| 409 | (none) | the mascotte's share link is switched off in the app | switch it on in the app |
| 400 | (none) | a field is wrong; error names it | fix 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):
| field | type | meaning |
|---|---|---|
| mascotte | number or string | Its id, or its exact name. |
| origin | string | The 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. |
| instructions | string | Up to 64,000 characters for this conversation only (a visitor's name, a case file, rules). |
| instructionsMode | string | "append" (default: added after the mascotte's own role) or "replace" (used instead of it). |
| greeting | string | Its first line, up to 600 characters. |
| language | string | A code like "en", "nl", "fr" or "zh". |
| view | string | "face" (the face and a call bar; your page draws the conversation) or "full" (with a chat panel, the default). |
| minutes | integer | 1 to 120, default 30. Never more than what is left of the key's minutes today. |
| resolution | string | "normal" (512 px, default) or "hd" (640 px, sharper and slower). |
| renderQuality | string | "best" or "fast" (about twice as quick, a little softer). |
| framing | string | "as-is" (the whole picture) or "auto" (zooms in on the face). |
| movementStyle | integer | 0 to 2147483647: a different way of moving the head. |
| restingLoop | integer | 1 to 6: how long the face rests between answers, about 1.3 s a step. |
| interrupt | boolean | true lets the visitor talk over the mascotte. Default false. |
| micSensitivity | string | "low", "normal" or "high". |
| replyLength | string | "short", "medium" or "long". |
| mode | string | "full" (our language model and voice, the default) or "own_ai" (yours, section 7). |
| llmProvider | string | The id of your own language model, like "prv_12" (section 7). |
| voiceProvider | string | The id of your own voice, like "prv_13" (section 7). |
| voiceEndpoint | string | An https address of your own voice service, given per session (section 7). Not with voiceProvider. |
| voiceSecret | string | 16 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):
- loading: the frame is fetching the mascotte.
- ready: loaded; the visitor can press Start.
- started: the call started. Sound only plays after this (browsers need one tap from the visitor).
- message: { role: "user" or "avatar", text, mode, at }. mode is "voice", "typed", "api", "said", "welcome" (the first line) or null (a generated answer).
- turn-end: { role, at }: the mascotte finished speaking; the visitor's turn.
- ended: the visitor hung up or the session ended.
- rated: { stars } if the visitor rated the call afterwards.
- error: { message, reason }. reason "voice" or "llm": your own provider failed; "busy": the key is paused or out of minutes; none: the session is not active.
Commands (after "started"):
- m.send(text): ask the mascotte, as if the visitor said it (up to 4,000 characters).
- m.say(text): the mascotte says exactly this; nothing is generated.
- m.end(): hang up.
- m.destroy(): remove the frame and its listeners.
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:
- list_characters: the characters: number, name, start of the role, language, whether they can talk (video), a thumbnail URL.
- get_character { character }: role, instructions, greeting, language and voice.
- create_character { description, name?, gender?, age?, style?, role?, instructions?, greeting?, language? }: four face options and a draft id. Nothing is saved until choose_face.
- choose_face { option, draft? , character? }: saves the new character with that face, or gives an existing one a new look.
- restyle_character { character, change, style? }: four new looks from one sentence, kept in the Lookbook.
- update_character { character, role?, instructions?, greeting?, language?, voice? }: only the fields sent change.
- start_session { character, origin?, minutes?, language?, greeting?, instructions?, view? }: a live conversation; answers the address to open or embed and when it ends.
- get_usage: this key's minutes and sessions today and this month, against its limits.
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):
- 2 conversations at once (429 concurrency_limit).
- 120 minutes a day, reset at 00:00 UTC (429 daily_limit). A session never runs past what is left.
- 10 sessions started a minute (429 rate_limit).
- 600 requests an hour to any /api/v1 route (429 rate_limit).
The API is free during the beta.
10. Privacy
- Mascotte keeps no transcript of API conversations. The lines go only to the
originyou gave. - The words do pass through the language model and the voice (ours, or yours in own_ai mode), as in every conversation.
- The visitor's microphone is used only after they press Start in the frame.
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.