Skip to content
Masko logomasko
Docs
QuickstartAPI reference
Documentation

List & Browse

Canonical routes use /v1/mascots. Canonical resource fields and filters use mascot_id. On shared routes such as /v1/assets, send Masko-API-Version: 2026-09-26; unversioned requests retain the legacy response for existing clients.

Browse your projects, mascots, and assets. Use these endpoints to find resource IDs, check generation status, and retrieve CDN URLs.

List Projects

Projects are the top-level container. Each project can hold multiple mascots.

curl https://api.masko.ai/v1/projects \
  -H "Authorization: Bearer masko_YOUR_API_KEY" \
  -H "Masko-API-Version: 2026-09-26"

# Response:
# {
#   "data": [
#     {
#       "id": "04dae799-dd9a-4296-ba86-9e3913c2f8d1",
#       "name": "My SaaS",
#       "organization_id": null,
#       "created_at": "2026-01-15T08:00:00Z",
#       "updated_at": "2026-01-15T08:00:00Z"
#     }
#   ],
#   "meta": { "pagination": { "total": 1, "limit": 50, "offset": 0, "has_more": false } }
# }

List Mascots

List all mascots, optionally filtered by project. Each mascot represents one mascot character.

# All mascots
curl https://api.masko.ai/v1/mascots \
  -H "Authorization: Bearer masko_YOUR_API_KEY" \
  -H "Masko-API-Version: 2026-09-26"

# Filter by project
curl "https://api.masko.ai/v1/mascots?project_id=75270a54-f2f9-58e5-83c0-8575c720ca86" \
  -H "Authorization: Bearer masko_YOUR_API_KEY" \
  -H "Masko-API-Version: 2026-09-26"

# Response:
# {
#   "data": [
#     {
#       "id": "f9503022-a991-46ea-bf8c-d628c921b6b0",
#       "project_id": "04dae799-dd9a-4296-ba86-9e3913c2f8d1",
#       "name": "Fox Mascot",
#       "type": "mascot",
#       "is_published": true,
#       "public_slug": "fox-mascot-a1b2c3d4",
#       "user_prefix": "fda8417d",
#       "created_at": "2026-02-01T10:00:00Z"
#     }
#   ],
#   "meta": { "pagination": { "total": 1, "limit": 50, "offset": 0, "has_more": false } }
# }

Mascot Detail

Get full details of a single mascot, including its configuration with style card and reference settings.

curl https://api.masko.ai/v1/mascots/8bf14263-eabc-58a4-80f6-be9e4f7bceeb \
  -H "Authorization: Bearer masko_YOUR_API_KEY" \
  -H "Masko-API-Version: 2026-09-26"

# Response:
# {
#   "data": {
#     "id": "f9503022-a991-46ea-bf8c-d628c921b6b0",
#     "name": "Fox Mascot",
#     "type": "mascot",
#     "project_id": "04dae799-dd9a-4296-ba86-9e3913c2f8d1",
#     "slug": "fox-mascot-a1b2c3d4",
#     "config": {
#       "prompt": "A friendly fox character for our SaaS",
#       "reference_asset_ids": ["e906ebb5-deb1-4010-82f9-f0182a3812e0"],
#       "style_card": null,
#       "caution_list": []
#     },
#     "cdn_status": [],
#     "created_at": "2026-02-01T10:00:00Z",
#     "updated_at": "2026-03-15T16:20:00Z"
#   }
# }

List Items

Items are individual poses or assets within a mascot. Each item can have multiple asset types (image, animation, logo).

curl https://api.masko.ai/v1/mascots/8bf14263-eabc-58a4-80f6-be9e4f7bceeb/items \
  -H "Authorization: Bearer masko_YOUR_API_KEY" \
  -H "Masko-API-Version: 2026-09-26"

# Response:
# {
#   "data": [
#     {
#       "id": "b646b856-5832-49f4-90bf-9c41a50515b3",
#       "name": "Idle",
#       "type": "image",
#       "prompt": "idle pose",
#       "public_slug": "idle",
#       "created_at": "2026-02-01T10:05:00Z"
#     }
#   ],
#   "meta": { "pagination": { "total": 1, "limit": 50, "offset": 0, "has_more": false } }
# }

Check Asset Status

List all assets in a mascot with their current status. Useful for checking which generations are still in progress.

curl https://api.masko.ai/v1/mascots/8bf14263-eabc-58a4-80f6-be9e4f7bceeb/assets \
  -H "Authorization: Bearer masko_YOUR_API_KEY" \
  -H "Masko-API-Version: 2026-09-26"

# Response:
# {
#   "data": [
#     {
#       "id": "e906ebb5-deb1-4010-82f9-f0182a3812e0",
#       "type": "image",
#       "status": "completed",
#       "file_url": "https://storage.googleapis.com/...",
#       "cdn_url": "https://assets.masko.ai/fda8417d/fox-mascot/idle.png",
#       "item_id": "b646b856-5832-49f4-90bf-9c41a50515b3",
#       "mascot_id": "f9503022-a991-46ea-bf8c-d628c921b6b0",
#       "created_at": "2026-02-01T10:05:00Z"
#     }
#   ],
#   "meta": { "pagination": { "total": 1, "limit": 50, "offset": 0, "has_more": false } }
# }

Published assets include cdn_url when a CDN URL exists. Assets without CDN publishing still include a signed file_url when available. For metadata-only polling or inventory views, add ?include_file_urls=false to skip signed file_url generation while keeping cdn_url.

CDN Export JSON

Use the CDN export endpoint when you want the same hosted-link JSON shown in the mascot page's Get Links → Export JSON panel. This endpoint is built from published cdn_assets, so it includes pose items that have video loops attached even when the item itself is not typed as an animation.

curl https://api.masko.ai/v1/mascots/8bf14263-eabc-58a4-80f6-be9e4f7bceeb/cdn-export \
  -H "Authorization: Bearer masko_YOUR_API_KEY" \
  -H "Masko-API-Version: 2026-09-26"

# Response:
# {
#   "mascot": "Fox Mascot",
#   "items": [
#     {
#       "name": "card-sit",
#       "image": "https://assets.masko.ai/fda8417d/fox-mascot/card-sit.png",
#       "transparent_image": "https://assets.masko.ai/fda8417d/fox-mascot/card-sit-transparent.png",
#       "animations": [
#         {
#           "video": "https://assets.masko.ai/fda8417d/fox-mascot/card-sit.mp4",
#           "transparent_video_webm": "https://assets.masko.ai/fda8417d/fox-mascot/card-sit.webm",
#           "transparent_video_mov": "https://assets.masko.ai/fda8417d/fox-mascot/card-sit.mov",
#           "transparent_video_android": "https://assets.masko.ai/fda8417d/fox-mascot/card-sit-android.mp4"
#         }
#       ]
#     }
#   ]
# }

The export also includes stickers, an array of transparent PNG URLs, and interactions, an array of complete cursor followers. Each interaction contains version, id, name, kind: "cursor-follower", width, height, manifest_url, and frames. The nine frame keys are up-left, up, up-right, left, center, right, down-left, down, and down-right; each points to a hosted lossless WebP. These are CDN URLs, not expiring signed preview URLs.

Generate cursor followers with POST /v1/mascots/:id/interactive or in the web app's Interactive tab. After enabling hosting, use Get Links → Update links to publish older sets, then fetch this export. Only complete hosted sets appear. The downloaded React component accepts an interaction object as its config prop.

Use /v1/mascots/:id/items and /v1/mascots/:id/assets for raw metadata, item IDs, asset IDs, prompts, and status checks. Use /v1/mascots/:id/cdn-export for the clean copy/paste export format.

If asset hosting is disabled, the mascot is unpublished, or no CDN assets are available yet, the endpoint returns 409 cdn_export_not_ready instead of an empty export. Enable asset hosting and publish/sync the mascot before retrying.

Items, Assets, and Deletion

Individual items can be renamed or deleted via:

  • PATCH /v1/mascots/:id/items/:itemId - body { name?, prompt? }
  • DELETE /v1/mascots/:id/items/:itemId

Assets are also exposed as a first-class resource:

  • GET /v1/assets - list your assets with pagination; add include_file_urls=false for metadata-only lists
  • GET /v1/assets/:id - get a single asset
  • DELETE /v1/assets/:id - archive an asset (soft delete)

Mascot variants

Variants use the mascot's project permissions. Organization owners and admins, and members with access to the project, can create, edit, generate, and approve a teammate's variants. API keys must belong to the mascot's workspace. Generation records the requesting user and charges the organization balance for a team mascot; the variant's original creator stays unchanged.

A variant is a named generation context for one mascot. It can describe a different look, personality direction or habits, alongside its approved reference image. Create and approve variants in the mascot page's Context & References panel or through the variant authoring endpoints described below. Editing a context affects future generations. Existing pose jobs retain the context captured when they were generated.

The paginated response includes id, name, description, approved_at, reference_asset_id and canvas_id. A null approved_at indicates a draft.

Pass an approved variant_id when generating:

{
  "type": "image",
  "name": "A curious detective",
  "variant_id": "VARIANT_UUID",
  "image_prompt": "Leaning forward with a curious expression."
}

Send this body to POST /v1/mascots/{id}/generate. Images, animations, edits, logos and scenes accept this field. Each request in /generate-batch can select a different variant. For a new pose, omission selects Original. With an explicit source image or video, omission uses that asset’s saved context. Neither follows the active playback variant. Draft variants return 409; a variant outside the requested mascot returns 404. An ordinary animation’s source must match an explicitly selected variant; a mismatch returns 409 before charging.

For a transition, supply source_image_asset_id and end_image_asset_id. The poses may belong to different variants. A prompt writer receives both images and their separately labelled before/after contexts, then writes the movement between them. It uses each pose’s saved context where available, so later edits do not change an existing pose’s meaning. Uploaded references without a generation receipt use their associated context at submission time; ambiguous associations are rejected. Inspect the resulting job’s generation_context.transition for both endpoints, the writer output and final video prompt. A cross-variant transition has variant_id: null, with each role recorded separately. Reversing a transition swaps the roles and does not call the prompt writer again.

Action and scene suggestions also accept variant_id. Omit it for Original.

For graph generation, use the variant's canvas_id with the existing canvas endpoints. Its poses and movements use the approved context automatically. Generating does not activate a variant. Preview and activate it separately in the web app once its media is ready.

A playback canvas can combine Original and named-variant poses and animations from the same mascot. Its variant sets the default generation context; it does not restrict which existing poses the graph can play. Assigned assets keep their own generation history. Activation still requires completed, unarchived media from this mascot or assets retained by its accepted parent version.

When editing a transition with type: "edit", source_video_asset_id and edit_instructions, the source clip keeps its saved before/after identities. For example, making the movement more playful still starts as Original and ends as Detective. Both pose images guide the video editor in that order. An explicit variant_id must match an endpoint; it does not restyle the whole clip. The job exposes your requested edit under generation_context.transition_edit.

Video edits run at 720p. The source clip must be 4–30 seconds long; its duration and aspect ratio are preserved. Cost remains 5 credits per source second, rounded up to a whole credit. Existing queued edits retain their original execution settings.

Create a variant through v1

Choose one of three starting points in the app: Generate, Upload image, or Choose image. Generate starts from the currently selected approved variant (Original when none is selected). You review and approve its new reference before generating poses. Upload and Choose image use the selected image directly when you click Create variant.

The same flow is available through REST:

  1. POST /v1/mascots/{id}/variants with a client-generated id, name, description, and optional source_variant_id. Omit the source for Original. The source context and references are frozen into the draft.
  2. POST /v1/mascots/{id}/variants/{variantId}/reference with { "operation_id": "UUID" }. This costs 1 credit and returns job_id and candidate_id. Reuse the operation ID to retry the same job.
  3. Poll GET /v1/jobs/{jobId}. Read GET /v1/mascots/{id}/variants/{variantId} to inspect candidate previews.
  4. POST /v1/mascots/{id}/variants/{variantId}/approve with { "candidate_id": "UUID" } to approve your choice.
  5. Pass that variant_id to the existing /generate endpoint for poses and animations. The approved variant also has a canvas_id. Approval does not activate playback or generate additional media.

To use an image you already have, add reference_asset_id in step 1. Use a completed image from the same mascot or your unassigned image from POST /v1/upload. The uploaded asset is attached to this mascot. This creates an approved variant without generating a reference and without a credit charge; skip steps 2–4. Archived, unfinished and other-mascot images are rejected.

Reuse the creation id only with the same inputs. Creating a draft is free. Only its creator may generate and approve its candidate references.