Mascotbot Avatars API | Mascot Bot SDK

A small public HTTP API that lists ready-made Mascotbot avatars (Rive .riv files) and serves their bytes plus per-version metadata. It is not an npm registry — just a manifest + binaries. Read access is public; no key required. The intended flow: fetch the .riv once, self-host it from your own CDN/origin, and drive Rive using the per-version metadata.

Base URL: https://license.mascot.bot

Concepts

Avatar — a mascot identified by an id (e.g. notion-guy), with one or more versions.
Version — an immutable (id, version) pair where version is semver x.y.z. The bytes for a published version never change; publishers ship updates as new versions. Old versions are retained.
latest — the highest semver of an avatar. What download serves when no version is requested.
Metadata — a freeform JSON object attached to each version, returned verbatim. There is no fixed schema — different .riv files expose different artboards, state machines, and inputs, so the shape is whatever the publisher set. Mascotbot’s own mascots mirror an artboard / stateMachine / customization shape; treat any field as optional.

List avatars

GET /v1/avatars

Returns the manifest. Response is Cache-Control: public, max-age=60; an empty pool is a valid 200 with "avatars": [].

{
  "schema": 2,
  "updatedAt": 1747000000000,
  "avatars": [
    {
      "id": "notion-guy",
      "name": "Notion Guy",
      "description": null,
      "latest": "1.0.0",
      "metadata": { /* latest version's metadata, or null */ },
      "downloadUrl": "https://license.mascot.bot/v1/avatars/notion-guy/download",
      "versions": [
        {
          "version": "1.0.0",
          "sha256": "651ab97684ea…",
          "fileSize": 218080,
          "createdAt": 1747000000000,
          "metadata": { /* freeform, publisher-defined */ },
          "downloadUrl": "https://license.mascot.bot/v1/avatars/notion-guy/download?version=1.0.0"
        }
      ]
    }
  ]
}

Download a `.riv`

GET /v1/avatars/<id>/download              # serves `latest`
GET /v1/avatars/<id>/download?version=1.0.0 # serves a pinned version

200 → the raw .riv (application/octet-stream, Content-Disposition: attachment).
X-Avatar-Version: <served version> is set on every response.
A pinned ?version= response is Cache-Control: public, max-age=31536000, immutable — safe to cache forever. The unversioned latest response is max-age=300 (it can move when a new version ships).
HEAD is supported.

Recommended integration pattern

Fetch the manifest once

Poll on your own cadence (it changes only when a new version ships).

Pick the avatar + version

Pin a version for reproducibility, or follow latest for auto-updates.

Download the .riv and self-host it

Store it on your own CDN/origin keyed by id@version (or by sha256). Pinned versions are immutable — you never need to re-fetch. Do not serve license.mascot.bot to end users on every page load.

Drive Rive from the metadata

The freeform metadata tells your renderer how to wire the file — artboard, stateMachine, available inputs, customization controls.

const API = "https://license.mascot.bot";

const manifest = await fetch(`${API}/v1/avatars`).then(r => r.json());
const avatar   = manifest.avatars.find((a: any) => a.id === "notion-guy");
const version  = avatar.latest; // or pin "1.0.0"

// Download once → store on your own hosting.
const riv = await fetch(
  `${API}/v1/avatars/notion-guy/download?version=${version}`,
).then(r => r.arrayBuffer());
await myCdn.put(`mascots/notion-guy@${version}.riv`, riv);

// Wire Rive from metadata (shape is publisher-defined).
const md = avatar.metadata ?? {};
new Rive({
  src: `https://my-cdn/mascots/notion-guy@${version}.riv`,
  artboard:      md.artboard,
  stateMachines: md.stateMachine,
  // md.customization → build your UI controls (type / min / max / default)
});

In the React SDK, the same flow ends with passing your self-hosted URL to <Mascot src={…}> and reading md.artboard / md.stateMachine from the manifest — see Rive co-existence for the input-ownership contract.

Variants — same character, different `.riv`

Some characters ship as multiple avatars because the standalone and embeddable-widget builds are genuinely different files with different Rive wiring. They are cross-linked in metadata and you pick the one matching how you render it:

`id`	use	artboard	stateMachine
`notion-guy`	standalone hosting	`Character`	`InLesson`
`notion-guy-widget`	embeddable widget	`Widget`	`mascotStateMachine`

The metadata on each one carries the full customization schema for that variant; the API doesn’t merge them.

Versioning

A published (id, version) is immutable — to change an avatar, the publisher ships a new version, and clients that pinned the old one keep working unchanged. latest is the highest semver; clients that follow it get updates automatically, clients that pin a version are stable. Pinned download URLs are immutable and long-cached, so they are safe to bake into your own CDN keyed by id@version or sha256.

Errors

JSON { "code": "...", "message": "..." }:

Status	`code`	Meaning
404	`avatar_not_found`	no such `id`
404	`version_not_found`	`id` exists, that `version` doesn’t
404	`avatar_binary_missing`	manifest entry exists but the binary is gone — report it
404	`not_found`	unknown route
405	`method_not_allowed`	non-`GET`/`HEAD` on a read route
500	`manifest_corrupt`	server-side; surface a friendly retry

Quick reference


List	`GET /v1/avatars` — public, 60 s cache
Download latest	`GET /v1/avatars/<id>/download`
Download pinned	`GET /v1/avatars/<id>/download?version=x.y.z` — immutable
Base URL	`https://license.mascot.bot`

Ready-made mascots

The catalog of characters available through this API.

Rive co-existence

The input-ownership contract once a .riv is rendered.

React SDK intro

Wiring a downloaded .riv into <Mascot>.

Getting Started

Core concepts

React SDK

Core SDK (vanilla)

Realtime providers

Reference

Ready-made Mascots

Mascotbot Avatars API - Ready-Made Mascot .riv Distribution

Concepts

List avatars

Download a `.riv`

Recommended integration pattern

Variants — same character, different `.riv`

Versioning

Errors

Quick reference

Next

Ready-made mascots

Rive co-existence

React SDK intro

​Concepts

​List avatars

​Download a .riv

​Recommended integration pattern

​Variants — same character, different .riv

​Versioning

​Errors

​Quick reference

​Next

Ready-made mascots

Rive co-existence

React SDK intro

Concepts

List avatars

Download a `.riv`

Recommended integration pattern

Variants — same character, different `.riv`

Versioning

Errors

Quick reference

Next