{
  "openapi": "3.0.3",
  "info": {
    "title": "Mascotte API",
    "version": "1.0.0-beta",
    "description": "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 url with https://app.mascotte.ai/web/embed.js. Call it from a server only: a request with an Origin header is refused (400, code browser). Keys are made by a signed-in person at https://app.mascotte.ai/web/developers.html and shown once. Full guide for people and AI agents: https://app.mascotte.ai/llms.txt",
    "contact": { "url": "https://app.mascotte.ai/docs/api" }
  },
  "externalDocs": { "description": "The full reference, including the embed events and the MCP server", "url": "https://app.mascotte.ai/llms.txt" },
  "servers": [ { "url": "https://app.mascotte.ai", "description": "Mascotte" } ],
  "security": [ { "bearerKey": [] } ],
  "tags": [
    { "name": "mascottes", "description": "The key owner's video avatars" },
    { "name": "sessions", "description": "Conversations to show in a page" },
    { "name": "usage", "description": "The key's use against its limits" },
    { "name": "mcp", "description": "Model Context Protocol server for AI assistants" }
  ],
  "paths": {
    "/api/v1/mascottes": {
      "get": {
        "tags": ["mascottes"],
        "operationId": "listMascottes",
        "summary": "The key owner's video mascottes, newest first",
        "responses": {
          "200": { "description": "The list", "content": { "application/json": { "schema": {
            "type": "object", "required": ["mascottes"],
            "properties": { "mascottes": { "type": "array", "items": { "$ref": "#/components/schemas/Mascotte" } } } } } } },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/api/v1/sessions": {
      "post": {
        "tags": ["sessions"],
        "operationId": "createSession",
        "summary": "Start a conversation and get the url to show it",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionRequest" },
          "example": { "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 } } } },
        "responses": {
          "201": { "description": "Started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewSession" } } } },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "403": { "$ref": "#/components/responses/Error" },
          "404": { "$ref": "#/components/responses/Error" },
          "409": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/api/v1/sessions/{id}": {
      "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^ses_[0-9]+$" }, "example": "ses_42" } ],
      "get": {
        "tags": ["sessions"],
        "operationId": "getSession",
        "summary": "A session's state",
        "responses": {
          "200": { "description": "The session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } } },
          "401": { "$ref": "#/components/responses/Error" },
          "404": { "$ref": "#/components/responses/Error" }
        }
      },
      "delete": {
        "tags": ["sessions"],
        "operationId": "endSession",
        "summary": "End a session now",
        "responses": {
          "200": { "description": "Ended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } } },
          "401": { "$ref": "#/components/responses/Error" },
          "404": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/api/v1/usage": {
      "get": {
        "tags": ["usage"],
        "operationId": "getUsage",
        "summary": "This key today and this month, against its limits",
        "responses": {
          "200": { "description": "Usage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Usage" } } } },
          "401": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/api/v1/mcp": {
      "post": {
        "tags": ["mcp"],
        "operationId": "mcp",
        "summary": "MCP server (Streamable HTTP, JSON responses, stateless)",
        "description": "JSON-RPC 2.0 messages of the Model Context Protocol (versions 2025-06-18, 2025-03-26, 2024-11-05). Tools: list_characters, get_character, create_character, choose_face, restyle_character, update_character, start_session, get_usage. A notification answers 202. GET and DELETE answer 405.",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" },
          "example": { "jsonrpc": "2.0", "id": 1, "method": "tools/list" } } } },
        "responses": {
          "200": { "description": "JSON-RPC response", "content": { "application/json": { "schema": { "type": "object" } } } },
          "202": { "description": "Accepted (a notification)" },
          "401": { "$ref": "#/components/responses/Error" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerKey": { "type": "http", "scheme": "bearer", "description": "An API key, mk_live_ followed by 32 characters. Server side only." }
    },
    "responses": {
      "Error": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
    },
    "schemas": {
      "Error": {
        "type": "object", "required": ["error"],
        "properties": {
          "error": { "type": "string", "description": "A sentence for a person; its wording can change." },
          "code": { "type": "string", "enum": ["browser", "key", "origin_required", "origin_not_allowed", "key_paused", "rate_limit", "concurrency_limit", "daily_limit", "not_video"] },
          "reason": { "type": "string", "description": "The same as code." }
        }
      },
      "Mascotte": {
        "type": "object", "required": ["id", "name"],
        "properties": {
          "id": { "type": "integer", "description": "Stays the same when it is renamed." },
          "name": { "type": "string" },
          "base": { "type": "string" },
          "updated": { "type": "string", "format": "date-time" }
        }
      },
      "SessionRequest": {
        "type": "object", "required": ["mascotte"],
        "properties": {
          "mascotte": { "oneOf": [ { "type": "integer" }, { "type": "string" } ], "description": "Its id, or its exact name." },
          "origin": { "type": "string", "description": "The page that shows it, like https://your-site.example (https, or http on localhost). Without it the frame sends no events." },
          "instructions": { "type": "string", "maxLength": 64000, "description": "For this conversation only." },
          "instructionsMode": { "type": "string", "enum": ["append", "replace"], "default": "append" },
          "greeting": { "type": "string", "maxLength": 600 },
          "language": { "type": "string", "example": "en" },
          "view": { "type": "string", "enum": ["face", "full"], "default": "full" },
          "minutes": { "type": "integer", "minimum": 1, "maximum": 120, "default": 30 },
          "resolution": { "type": "string", "enum": ["normal", "hd"], "default": "normal" },
          "renderQuality": { "type": "string", "enum": ["best", "fast"] },
          "framing": { "type": "string", "enum": ["as-is", "auto"] },
          "movementStyle": { "type": "integer", "minimum": 0, "maximum": 2147483647 },
          "restingLoop": { "type": "integer", "minimum": 1, "maximum": 6 },
          "interrupt": { "type": "boolean", "default": false },
          "micSensitivity": { "type": "string", "enum": ["low", "normal", "high"] },
          "replyLength": { "type": "string", "enum": ["short", "medium", "long"] },
          "mode": { "type": "string", "enum": ["full", "own_ai"], "default": "full" },
          "llmProvider": { "type": "string", "pattern": "^prv_[0-9]+$", "description": "Your own language model, stored on the Developers page." },
          "voiceProvider": { "type": "string", "pattern": "^prv_[0-9]+$", "description": "Your own voice, stored on the Developers page." },
          "voiceEndpoint": { "type": "string", "description": "An https address of your own voice service for this session. Not with voiceProvider." },
          "voiceSecret": { "type": "string", "minLength": 16, "maxLength": 256, "description": "Sent to voiceEndpoint as a Bearer token." }
        }
      },
      "NewSession": {
        "type": "object", "required": ["id", "url", "expiresAt"],
        "properties": {
          "id": { "type": "string", "example": "ses_42" },
          "url": { "type": "string", "description": "Show this in the page (embed.js or an iframe). Safe to give to a browser." },
          "mascotte": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } },
          "expiresAt": { "type": "string", "format": "date-time" },
          "origin": { "type": "string", "nullable": true },
          "mode": { "type": "string", "enum": ["full", "own_ai"] },
          "minutes": { "type": "integer" }
        }
      },
      "Session": {
        "type": "object", "required": ["id", "state"],
        "properties": {
          "id": { "type": "string" },
          "state": { "type": "string", "enum": ["waiting", "open", "ended", "expired"] },
          "created": { "type": "string", "format": "date-time" },
          "opened": { "type": "string", "format": "date-time", "nullable": true },
          "ended": { "type": "string", "format": "date-time", "nullable": true },
          "expiresAt": { "type": "string", "format": "date-time" },
          "minutes": { "type": "integer", "description": "Started minutes from opening to hang-up." },
          "mode": { "type": "string", "enum": ["full", "own_ai"] }
        }
      },
      "Usage": {
        "type": "object",
        "properties": {
          "key": { "type": "object", "properties": { "name": { "type": "string" } } },
          "today": { "type": "object", "properties": { "minutes": { "type": "integer" }, "sessions": { "type": "integer" }, "atOnce": { "type": "integer" } } },
          "month": { "type": "object", "properties": { "minutes": { "type": "integer" }, "sessions": { "type": "integer" } } },
          "limits": { "type": "object", "properties": { "maxConcurrent": { "type": "integer" }, "maxDailyMinutes": { "type": "integer" },
                                                         "createPerMinute": { "type": "integer" }, "origins": { "type": "array", "items": { "type": "string" } } } },
          "paused": { "type": "boolean" },
          "free": { "type": "boolean" }
        }
      }
    }
  }
}
