API

Render new scenes of a locked mascot from your own scripts, CI jobs and AI agents. One key, one endpoint, and every image is checked against the locked identity before you get it — the same guarantee the app gives you.

1. Get a key

In the app, open Settings → API keys, pick the mascot the key may render, and generate it. The key is shown once; copy it then. Each key renders exactly one mascot, so a key that leaks cannot touch the rest of your library. Revoke it any time from the same screen.

Send the key on every request in an Authorization: Bearer header, or as x-api-key.

2. Render a scene

One request, one image. The call returns when the render is done and has been checked, usually within a minute.

curl -X POST https://app.mascotline.dev/api/v1/render \
  -H "Authorization: Bearer mr_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "characterId": "the mascot this key is scoped to",
    "sceneText": "waving from a hot-air balloon over a city at sunrise",
    "clientRequestId": "any id you mint, unique per scene"
  }'

The answer describes the render:

{
  "id": "…",
  "status": "gated",
  "gateVerdict": "pass",
  "gateReasonNote": null,
  "storagePath": "renders/….png",
  "isDuplicateOf": null,
  "sceneText": "…",
  "createdAt": "…"
}

• The image is at https://app.mascotline.dev/api/storage/ followed by storagePath. The link needs no key.
• gateVerdict is pass when the scene matches the locked identity. On fail, gateReasonNote says what drifted; the product already retried on a stronger setting before answering. After the last retry the render comes back with status: "rejected" and is not charged again.
• Approving a render for reuse as a reference happens in the app, not through the key.

3. Never pay twice

clientRequestId is yours to mint, and it is the safety net: send the same id again — after a timeout, a crash, a retry loop — and you get the same render back, with no new charge. If the response never reached you, fetch it instead of rendering again:

curl "https://app.mascotline.dev/api/v1/render?clientRequestId=the-id-you-sent" \
  -H "Authorization: Bearer mr_your_key"

A scene identical to one you already rendered for the same mascot is also answered from the existing render; isDuplicateOf names it, and nothing is charged.

4. Credits

Each new render spends one credit from the account that owns the key. When the balance is empty the call answers 402 and nothing is rendered; top up in the app under Credits.

When a call is refused

5. Connect an AI agent

Agents that speak MCP — Claude Code, Cursor, Claude Desktop and others — connect to one URL with the same key and get your mascots as tools: list_mascots, get_mascot, list_renders, render_scene, get_render, and with the account scope also explore_mascot, lock_mascot, list_drafts and project_setup. Nothing to install.

Claude Code, one command:

claude mcp add --transport http mascotline https://app.mascotline.dev/api/mcp \
  --header "Authorization: Bearer mr_your_key"

Cursor, Claude Desktop and most others take the same thing as a config entry:

{
  "mcpServers": {
    "mascotline": {
      "url": "https://app.mascotline.dev/api/mcp",
      "headers": { "Authorization": "Bearer mr_your_key" }
    }
  }
}

In the app, a newly issued key comes with Add to Cursor and Add to VS Code buttons that carry the key for you, and the Claude Code command ready to copy.

Claude Desktop, claude.ai and ChatGPT take no key at all: add a custom connector with the URL https://app.mascotline.dev/api/mcp, sign in to Mascotline when asked, pick the mascot it may render, and approve. That approval creates a key named after the app under Settings → API keys; revoke it there to disconnect.

6. Working inside a project

An assistant that builds your product should carry the mascot with the project, not ask you to pick one on the web every time. Two things make that work: the account scope, and a small folder in the repo.

Account scope. When you approve a connector (or issue a key) choose All mascots in this account. The assistant can then list your mascots, read a mascot's locked identity with its pictures, render any of them, and create a new one — in chat, with your say-so at each paid step. A single-mascot key stays right for a CI job or a third party.

The folder. A project that uses a mascot keeps .mascotline/mascotline.json, committed to the repo. It holds ids and roles only, never a key:

{
  "version": 1,
  "account": "app.mascotline.dev",
  "mascots": [
    { "id": "…", "name": "Inky", "role": "primary" }
  ],
  "defaults": { "mascot": "…" }
}

The connector's own instructions teach the assistant the routine, so you do not have to:

• Opening a project: read the file, confirm each mascot with get_mascot, use those mascots for any image work.
• No file yet: list what the account has and offer one, or offer to create one — explore_mascot shows four candidate looks as images, lock_mascot locks the one you choose and hands back the file to write. project_setup writes the file for mascots you already have.
• Money: exploring, locking and rendering each say what they cost, and the assistant is told never to spend without you agreeing. Reads are free. Anything it creates is in the app too: drafts under In progress, keys under Settings → API keys.

The folder is yours to grow: scene presets, a brand palette, cached approved renders — whatever your build needs beside the ids.

Then just ask for a scene. render_scene answers with the image itself and the check verdict, so the assistant can look at what it made; it takes the same clientRequestId safety net as the plain call.

Good to know

• Describe the scene, not the character: pose, setting, action, mood. The mascot's look comes from its locked identity.
• Each key may make 30 calls per minute across the render call, the lookup and the agent tools. A burst answers 429 with a Retry-After header — wait that long and retry with the same clientRequestId. Other keys are not affected.
• The plain calls and the agent tools are the same surface: a render made by an agent shows up in the app like any other, and the app's approve step is where a render becomes a reference.