Canvas Templates

Template application below uses the legacy /v1/collections API. Canonical POST /v1/canvases creates an empty draft and does not accept template_id. For new integrations, create a project canvas, then PATCH its graph with expected_graph_hash; see Canvas. Existing template consumers remain supported during migration.

Templates are blueprints for canvases. They define the nodes (poses), edges (transitions), conditions, and prompts - but no generated assets. When you apply a template, Masko creates items and kicks off image generation for every node.

What Templates Provide

A template contains the full graph structure: node positions, names, image prompts, edge connections, conditions, durations, and input definitions. It does not contain any generated assets. When applied, the template creates new items in the mascot, generates images for each node, and saves the graph to the canvas. You then use generate-all to create all the transition animations.

Available templates

Use the list endpoint to discover current built-in and saved templates. Templates such as claude-code-4state are compatibility scaffolds. For a new app, choose a graph that fits its actual states and reactions, then inspect generation costs with a dry-run.

List Templates

Fetch all available templates - both built-in and your own saved templates. Use the source query parameter to filter.

# All templates (built-in + yours)
curl https://api.masko.ai/v1/canvas-templates \
  -H "Authorization: Bearer masko_YOUR_API_KEY"

# Only built-in templates
curl "https://api.masko.ai/v1/canvas-templates?source=builtin" \
  -H "Authorization: Bearer masko_YOUR_API_KEY"

# Only your saved templates
curl "https://api.masko.ai/v1/canvas-templates?source=mine" \
  -H "Authorization: Bearer masko_YOUR_API_KEY"

Apply a Template

Create a new canvas from a template in one call. The endpoint creates items for each node, generates images, and saves the graph. The response includes a node_mapping that maps template node keys to the created item and asset IDs, plus a list of generation jobs.

curl -X POST https://api.masko.ai/v1/collections/MASCOT_ID/canvases \
  -H "Authorization: Bearer masko_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Main Canvas",
    "template_id": "claude-code-4state"
  }'

Customize with Overrides

Pass node_overrides and edge_overrides to customize template prompts and names without modifying the template itself. Node overrides are keyed by the template's node key. Edge overrides are keyed by source->target format.

curl -X POST https://api.masko.ai/v1/collections/MASCOT_ID/canvases \
  -H "Authorization: Bearer masko_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Main Canvas",
    "template_id": "claude-code-4state",
    "node_overrides": {
      "idle": {
        "name": "Resting",
        "imagePrompt": "sitting peacefully on a rock, eyes half-closed"
      },
      "celebrating": {
        "imagePrompt": "doing a backflip with sparkles"
      }
    },
    "edge_overrides": {
      "idle->thinking": {
        "description": "slowly standing up and scratching head"
      }
    }
  }'

Save Your Own

Save a template from an existing canvas or from a raw JSON graph definition. Set public: true to make it available to other users.

curl -X POST https://api.masko.ai/v1/canvas-templates \
  -H "Authorization: Bearer masko_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Widget Template",
    "description": "3-state sidebar widget with shared behavior inputs",
    "canvas_id": "CANVAS_ID",
    "collection_id": "MASCOT_ID",
    "public": false
  }'

Get or Update a Template

Fetch or rename one of your saved templates. Built-in templates are read-only.

curl https://api.masko.ai/v1/canvas-templates/tmpl_abc123 \
  -H "Authorization: Bearer masko_YOUR_API_KEY"

curl -X PATCH https://api.masko.ai/v1/canvas-templates/tmpl_abc123 \
  -H "Authorization: Bearer masko_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Widget v2",
    "description": "Updated description",
    "public": true
  }'