Skip to content
Masko logomasko
Docs
TerminalAPI reference
Documentation

API Changelog

Selected compatibility changes to the Masko v1 API are recorded here. Breaking changes are flagged clearly with a migration note.

Read the notes for any version that is newer than when you last integrated, then update your REST client against the current OpenAPI specification.

Current development

The repository includes hosted developer characters, revision-checked graph proposals, generation plans and recoverable runs, immutable runtime versions, and browser/device CLI authorization. See hosted characters, authentication, and terminal setup. Check the live OpenAPI specification for deployment availability.

1.14.0 - 2026-08-20

Added

  • GET /v1/collections/:id/canvases/:canvasId now returns status.nodes.failed and status.failed_nodes. Failed node and edge entries include the related job ID and a customer-safe error message.

Compatibility

  • status.nodes.pending still counts all incomplete nodes, including failed nodes. Existing polling clients keep their previous behavior and can adopt status.nodes.failed when ready.

1.6.0 - 2026-05-23

Added

  • GET /v1/collections/:id/cdn-export returns the same published CDN JSON shape as the collection page Get Links export modal. Use this for copy-paste app manifests; use /items and /assets for raw IDs, prompts, metadata, and status checks.

Changed

  • CDN export requests now fail clearly with 409 cdn_export_not_ready when asset hosting is disabled, the collection is not published, or no CDN assets have been published yet.

1.5.0 - 2026-05-16

Added

  • GET /v1/assets and GET /v1/collections/:id/assets now accept optional include_file_urls=false for faster metadata-only lists. Defaults are unchanged, so existing callers still receive signed file_url values.

1.2.0 - 2026-04-19

API cleanup pass. Applies one consistent convention across every endpoint: plural resources, verb endpoints only for one-shot actions, {data, meta?} response envelope, generation responses with data.poll_url, and path-parameter IDs instead of bodies.

Added

  • POST /v1/analyze - unified analysis endpoint. Body: {type: "image" | "url", image_url?, url?}. Replaces the two legacy endpoints.
  • GET /v1/collections/:id/suggestions - AI-suggested action names for a mascot collection. Read-only, no credits.
  • GET /v1/assets and GET /v1/assets/:id - first-class access to assets. Filter by collection_id, type, is_archived.
  • DELETE /v1/assets/:id - archive an asset (soft delete).
  • PATCH /v1/collections/:id/items/:itemId - update an item's name or prompt.
  • DELETE /v1/collections/:id/items/:itemId - archive an item.
  • DELETE /v1/collections/:id/canvases/:canvasId - delete a canvas.
  • PATCH /v1/canvas-templates/:id and GET /v1/canvas-templates/:id.
  • DELETE /v1/collections/:id/references/:assetId - remove a reference by path param.

Changed (breaking)

  • POST /v1/collections/:id/generate-batch - returns 202 Accepted with data.jobs, data.total_cost, and data.poll_url.
  • DELETE /v1/collections/:id/references - the asset ID moves from the body to the URL path. Old: DELETE /references with {asset_id} in body. New: DELETE /references/:assetId.
  • POST /v1/collections/:id/canvases - now accepts an optional template_id (plus node_overrides, edge_overrides). The legacy /canvases/:canvasId/from-template endpoint is removed - apply templates at creation time instead.
  • PUT /v1/collections/:id/canvases/:canvasId - now PATCH /v1/collections/:id/canvases/:canvasId. Body unchanged.
  • GET /v1/collections/:id/canvases/:canvasId/status - removed. The status object is now on the canvas GET response.
  • PATCH /v1/collections/:id/cdn-slug - removed. Set slug via PATCH /v1/collections/:id with {slug} in the body.
  • GET /v1/collections/:id/cdn-status - removed. The cdn_status array is now on GET /v1/collections/:id.
  • GET /v1/collections/:id/urls - removed. Use GET /v1/collections/:id/assets - URLs are already attached to each asset.
  • Paginated responses - pagination now lives under meta.pagination instead of top-level pagination. Shape is unchanged: {total, limit, offset, has_more}.
  • Async responses - poll_url now lives inside data (previously top-level). Clients that construct the poll URL from job_id are unaffected.

Removed

  • POST /v1/analyze-image - use POST /v1/analyze with {type: "image", image_url}.
  • POST /v1/analyze-url - use POST /v1/analyze with {type: "url", url}.
  • POST /v1/collections/:id/suggest-actions - use GET /v1/collections/:id/suggestions.

Not changed

  • POST /v1/collections/:id/generate - URL, body, and response are unchanged.
  • POST /v1/upload - unchanged.
  • GET /v1/jobs/:id - unchanged. Still supports ?wait=true&timeout=120.
  • Authentication and credit costs - all unchanged.

Migration checklist

  • POST /analyze-image callers: swap to POST /analyze with {type: "image", image_url}.
  • POST /analyze-url callers: swap to POST /analyze with {type: "url", url}.
  • POST /suggest-actions callers: swap to GET /suggestions. No body needed.
  • DELETE /references body callers: move asset_id from body to URL path.
  • cdn-slug / cdn-status / urls callers: read and write via the main collection endpoints.
  • Canvas from-template callers: pass template_id on POST /canvases instead.
  • Canvas PUT callers: change the method to PATCH.

Most customers will not need code changes if they only use POST /generate and GET /jobs/:id with the documented request and response shapes.

1.1.0 - 2026-04-10

  • Envelope enforcement: every v1 response now wraps data in {data} or {error: {code, message}}. Lists include pagination metadata.
  • Introduced the api-key permission levels: read, write, admin. New keys default to write.

1.0.0 - 2025-12-01

Initial public release of the Masko v1 API covering projects, collections, items, canvases, generation, jobs, webhooks, and credits.

How to follow updates

Application playback (requires coordinated deployment)

Added application management, publishable keys, restricted server secrets, and ten-minute playback sessions for owned private mascot versions. Existing version delivery also accepts a scoped playback token with its matching publishable key. Owner API keys and CLI auth remain separate.

The local application-playback release now uses workspace ownership without a per-application mascot allowlist. Removed the unreleased version allow/remove operations; each issued token still covers one requested immutable version. Developers now separates Applications, API keys and Webhooks.

Temporary mascot URLs

Added POST /v1/characters/{character}/access and SDK Masko.mascot(url) loading without a publishable key or callback. Default access resolves the latest prepared private version of the default canvas; optional version pinning remains. URLs carry opaque bearer tokens in their fragment, which SDKs move into authorization headers. Existing token records, expiry and ownership checks are reused, with no schema or credential changes. The dashboard now presents backend keys and a guide link. Legacy structured-access integrations remain supported. Offline playback of a loaded handle works; offline restart restoration remains pending. These changes are local and unpublished.