REST API reference

Generate and manage characters, assets, canvases, and hosted runtime versions. Expand an endpoint to see its request and response fields.

Production base: https://api.masko.ai/v1. The paths below already include /v1. Local development uses http://localhost:3000/api/v1.

This reference uses the repository’s generated OpenAPI specification. For deployed availability, read the live specification. Start with REST quickstart or authentication. Shared response envelopes and pagination are covered in requests and responses.

158 endpoints

GET/v1/canvasesList independently owned project canvases

Lists the canvases of one project, newest first. project_id is required. Without limit, offset or cursor every canvas is returned; with them, results are paged like other lists.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

project_idquery · required

string

Responses

200 Successful response

application/json

dataarray · required

Nested fields

objectstring · required

Values: "canvas"

idstring · uuid · required

project_idstring · uuid · nullable · required

mascot_idstring · uuid · nullable · required

namestring · required

graphobject · nullable · required

graph_content_hashstring · required

created_atstring · nullable · required

updated_atstring · nullable · required

400 Invalid input

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Authentication required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Write key required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Resource not found in credential workspace

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Revision conflict or retained history

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

422 Required release media unavailable

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "operationId": "listProjectCanvases",
  "tags": [
    "Canvases"
  ],
  "summary": "List independently owned project canvases",
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "project_id",
      "in": "query"
    }
  ],
  "responses": {
    "200": {
      "description": "Successful response",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "object": {
                      "type": "string",
                      "enum": [
                        "canvas"
                      ]
                    },
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "project_id": {
                      "type": "string",
                      "nullable": true,
                      "format": "uuid"
                    },
                    "mascot_id": {
                      "type": "string",
                      "nullable": true,
                      "format": "uuid"
                    },
                    "name": {
                      "type": "string"
                    },
                    "graph": {
                      "type": "object",
                      "nullable": true,
                      "additionalProperties": {
                        "nullable": true
                      }
                    },
                    "graph_content_hash": {
                      "type": "string"
                    },
                    "created_at": {
                      "type": "string",
                      "nullable": true
                    },
                    "updated_at": {
                      "type": "string",
                      "nullable": true
                    }
                  },
                  "required": [
                    "object",
                    "id",
                    "project_id",
                    "mascot_id",
                    "name",
                    "graph",
                    "graph_content_hash",
                    "created_at",
                    "updated_at"
                  ]
                }
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Invalid input",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "401": {
      "description": "Authentication required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "403": {
      "description": "Write key required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "404": {
      "description": "Resource not found in credential workspace",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "409": {
      "description": "Revision conflict or retained history",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "422": {
      "description": "Required release media unavailable",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  },
  "description": "Lists the canvases of one project, newest first. `project_id` is required. Without `limit`, `offset` or `cursor` every canvas is returned; with them, results are paged like other lists.",
  "x-masko-api-version": "2026-09-26"
}

POST/v1/canvasesCreate a project canvas with an initial mascot reference

Creates an empty draft canvas in a project, bound to a mascot you own or acquired from Marketplace. Send project_id, mascot_id and name; optional variant_id selects the appearance. Save the graph next with PATCH /v1/canvases/{canvasId}.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

Idempotency-Keyheader

Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.

string

Request body

application/json

project_idstring · uuid · required

mascot_idstring · uuid · required

namestring · required

Length: 1 to 120 characters

variant_idstring · uuid

Responses

201 Successful response

application/json

dataobject · required

Nested fields

objectstring · required

Values: "canvas"

idstring · uuid · required

project_idstring · uuid · nullable · required

mascot_idstring · uuid · nullable · required

namestring · required

graphobject · nullable · required

graph_content_hashstring · required

created_atstring · nullable · required

updated_atstring · nullable · required

400 Invalid input

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Authentication required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Write key required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Resource not found in credential workspace

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Revision conflict or retained history

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

422 Required release media unavailable

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "operationId": "createProjectCanvas",
  "tags": [
    "Canvases"
  ],
  "summary": "Create a project canvas with an initial mascot reference",
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "project_id": {
              "type": "string",
              "format": "uuid"
            },
            "mascot_id": {
              "type": "string",
              "format": "uuid"
            },
            "name": {
              "type": "string",
              "minLength": 1,
              "maxLength": 120
            },
            "variant_id": {
              "type": "string",
              "format": "uuid"
            }
          },
          "required": [
            "project_id",
            "mascot_id",
            "name"
          ],
          "additionalProperties": false
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Successful response",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "object": {
                    "type": "string",
                    "enum": [
                      "canvas"
                    ]
                  },
                  "id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "project_id": {
                    "type": "string",
                    "nullable": true,
                    "format": "uuid"
                  },
                  "mascot_id": {
                    "type": "string",
                    "nullable": true,
                    "format": "uuid"
                  },
                  "name": {
                    "type": "string"
                  },
                  "graph": {
                    "type": "object",
                    "nullable": true,
                    "additionalProperties": {
                      "nullable": true
                    }
                  },
                  "graph_content_hash": {
                    "type": "string"
                  },
                  "created_at": {
                    "type": "string",
                    "nullable": true
                  },
                  "updated_at": {
                    "type": "string",
                    "nullable": true
                  }
                },
                "required": [
                  "object",
                  "id",
                  "project_id",
                  "mascot_id",
                  "name",
                  "graph",
                  "graph_content_hash",
                  "created_at",
                  "updated_at"
                ]
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Invalid input",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "401": {
      "description": "Authentication required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "403": {
      "description": "Write key required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "404": {
      "description": "Resource not found in credential workspace",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "409": {
      "description": "Revision conflict or retained history",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "422": {
      "description": "Required release media unavailable",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  },
  "description": "Creates an empty draft canvas in a project, bound to a mascot you own or acquired from Marketplace. Send `project_id`, `mascot_id` and `name`; optional `variant_id` selects the appearance. Save the graph next with `PATCH /v1/canvases/{canvasId}`.",
  "parameters": [
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.",
      "schema": {
        "type": "string",
        "maxLength": 255
      }
    }
  ],
  "x-masko-api-version": "2026-09-26"
}

GET/v1/canvases/{canvasId}Read a canvas by its own project access

Returns the canvas draft: graph and its revision graph_content_hash. Send that hash as expected_graph_hash when you save. For generation progress use GET /v1/canvases/{canvasId}/status.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

canvasIdpath · required

string

Responses

200 Successful response

application/json

dataobject · required

Nested fields

objectstring · required

Values: "canvas"

idstring · uuid · required

project_idstring · uuid · nullable · required

mascot_idstring · uuid · nullable · required

namestring · required

graphobject · nullable · required

graph_content_hashstring · required

created_atstring · nullable · required

updated_atstring · nullable · required

400 Invalid input

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Authentication required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Write key required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Resource not found in credential workspace

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Revision conflict or retained history

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

422 Required release media unavailable

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "operationId": "getProjectCanvas",
  "tags": [
    "Canvases"
  ],
  "summary": "Read a canvas by its own project access",
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "canvasId",
      "in": "path"
    }
  ],
  "responses": {
    "200": {
      "description": "Successful response",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "object": {
                    "type": "string",
                    "enum": [
                      "canvas"
                    ]
                  },
                  "id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "project_id": {
                    "type": "string",
                    "nullable": true,
                    "format": "uuid"
                  },
                  "mascot_id": {
                    "type": "string",
                    "nullable": true,
                    "format": "uuid"
                  },
                  "name": {
                    "type": "string"
                  },
                  "graph": {
                    "type": "object",
                    "nullable": true,
                    "additionalProperties": {
                      "nullable": true
                    }
                  },
                  "graph_content_hash": {
                    "type": "string"
                  },
                  "created_at": {
                    "type": "string",
                    "nullable": true
                  },
                  "updated_at": {
                    "type": "string",
                    "nullable": true
                  }
                },
                "required": [
                  "object",
                  "id",
                  "project_id",
                  "mascot_id",
                  "name",
                  "graph",
                  "graph_content_hash",
                  "created_at",
                  "updated_at"
                ]
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Invalid input",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "401": {
      "description": "Authentication required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "403": {
      "description": "Write key required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "404": {
      "description": "Resource not found in credential workspace",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "409": {
      "description": "Revision conflict or retained history",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "422": {
      "description": "Required release media unavailable",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  },
  "description": "Returns the canvas draft: `graph` and its revision `graph_content_hash`. Send that hash as `expected_graph_hash` when you save. For generation progress use `GET /v1/canvases/{canvasId}/status`.",
  "x-masko-api-version": "2026-09-26"
}

PATCH/v1/canvases/{canvasId}Save a draft with optimistic concurrency

Replaces the whole graph. Send the latest graph_content_hash as expected_graph_hash; if the canvas changed since you read it, the request returns 409 and you should read it again.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

canvasIdpath · required

string

Request body

application/json

graphobject · required

expected_graph_hashstring · required

Length: 1 to unbounded characters

Responses

200 Successful response

application/json

dataobject · required

Nested fields

objectstring · required

Values: "canvas"

idstring · uuid · required

project_idstring · uuid · nullable · required

mascot_idstring · uuid · nullable · required

namestring · required

graphobject · nullable · required

graph_content_hashstring · required

created_atstring · nullable · required

updated_atstring · nullable · required

400 Invalid input

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Authentication required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Write key required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Resource not found in credential workspace

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Revision conflict or retained history

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

422 Required release media unavailable

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "operationId": "updateProjectCanvas",
  "tags": [
    "Canvases"
  ],
  "summary": "Save a draft with optimistic concurrency",
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "canvasId",
      "in": "path"
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "graph": {
              "type": "object",
              "additionalProperties": {
                "nullable": true
              }
            },
            "expected_graph_hash": {
              "type": "string",
              "minLength": 1
            }
          },
          "required": [
            "graph",
            "expected_graph_hash"
          ],
          "additionalProperties": false
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Successful response",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "object": {
                    "type": "string",
                    "enum": [
                      "canvas"
                    ]
                  },
                  "id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "project_id": {
                    "type": "string",
                    "nullable": true,
                    "format": "uuid"
                  },
                  "mascot_id": {
                    "type": "string",
                    "nullable": true,
                    "format": "uuid"
                  },
                  "name": {
                    "type": "string"
                  },
                  "graph": {
                    "type": "object",
                    "nullable": true,
                    "additionalProperties": {
                      "nullable": true
                    }
                  },
                  "graph_content_hash": {
                    "type": "string"
                  },
                  "created_at": {
                    "type": "string",
                    "nullable": true
                  },
                  "updated_at": {
                    "type": "string",
                    "nullable": true
                  }
                },
                "required": [
                  "object",
                  "id",
                  "project_id",
                  "mascot_id",
                  "name",
                  "graph",
                  "graph_content_hash",
                  "created_at",
                  "updated_at"
                ]
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Invalid input",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "401": {
      "description": "Authentication required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "403": {
      "description": "Write key required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "404": {
      "description": "Resource not found in credential workspace",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "409": {
      "description": "Revision conflict or retained history",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "422": {
      "description": "Required release media unavailable",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  },
  "description": "Replaces the whole graph. Send the latest `graph_content_hash` as `expected_graph_hash`; if the canvas changed since you read it, the request returns 409 and you should read it again.",
  "x-masko-api-version": "2026-09-26"
}

DELETE/v1/canvases/{canvasId}Delete a canvas without retained history

Deletes a canvas that has no saved checkpoints or releases. A canvas with history returns 409.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

canvasIdpath · required

string

Responses

204 Deleted

400 Invalid input

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Authentication required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Write key required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Resource not found in credential workspace

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Revision conflict or retained history

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

422 Required release media unavailable

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "operationId": "deleteProjectCanvas",
  "tags": [
    "Canvases"
  ],
  "summary": "Delete a canvas without retained history",
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "canvasId",
      "in": "path"
    }
  ],
  "responses": {
    "204": {
      "description": "Deleted",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Invalid input",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "401": {
      "description": "Authentication required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "403": {
      "description": "Write key required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "404": {
      "description": "Resource not found in credential workspace",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "409": {
      "description": "Revision conflict or retained history",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "422": {
      "description": "Required release media unavailable",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  },
  "description": "Deletes a canvas that has no saved checkpoints or releases. A canvas with history returns 409.",
  "x-masko-api-version": "2026-09-26"
}

GET/v1/canvases/{canvasId}/statusRead canvas generation progress

Generation progress for a canvas. Poll it every 15 to 30 seconds after POST /v1/canvases/{canvasId}/generate-all. Read-only keys can call it, and it never changes the canvas. status.generation.nodes and status.generation.edges count total, completed, pending and failed parts. Pending means neither finished nor failed. Stop polling when status.generation.ready is true: every node image and edge video exists. The canvas plays in the editor once status.preview.ready is also true. If status.preview.waiting_edges is above 0, keep polling because derivatives are still being prepared. If status.preview.repairable is true, call POST /v1/canvases/{canvasId}/repair with dry_run: true first. If any failed count is above 0, read status.failed_nodes and status.failed_edges. Each entry has the part id, its job_id and a customer-safe error. A retry is a new paid attempt, so ask before retrying. Returns 409 when the canvas has no mascot generation context.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

canvasIdpath · required

string

Responses

200 Successful response

application/json

dataobject · required

Nested fields

objectstring · required

Values: "canvas_status"

canvas_idstring · uuid · required

graph_content_hashstring · required

statusobject · required

Nested fields

generationobject · required

Nested fields

readyboolean · required

nodesobject · required

Nested fields

totalnumber · required

completednumber · required

pendingnumber · required

Incomplete node count. Includes failed nodes for backward compatibility; inspect failed for the terminal subset.

failednumber · required

edgesobject · required

Nested fields

totalnumber · required

completednumber · required

pendingnumber · required

failednumber · required

previewobject · required

Nested fields

readyboolean · required

repairableboolean · required

repairable_edgesnumber · required

waiting_edgesnumber · required

missing_edgesnumber · required

missing_formatsarray · required

Nested fields

string · webm, hevc

variantsobject · required

Nested fields

sizesarray · required

Nested fields

string

missingarray · required

Nested fields

edge_idstring · required

sizestring · required

formatsarray · required

Nested fields

string · webm, hevc

failed_nodesarray · required

Nested fields

node_idstring · required

job_idstring · uuid · nullable · required

errorstring · required

failed_edgesarray · required

Nested fields

edge_idstring · required

job_idstring · uuid · nullable · required

errorstring · required

edge_mediaarray

Nested fields

edge_idstring · required

sourcestring · required

targetstring · required

video_asset_idstring · uuid · nullable · required

baseobject · required

Nested fields

video_readyboolean · required

webm_readyboolean · required

hevc_readyboolean · required

preview_readyboolean · required

derivatives_in_flightboolean · required

source_job_idstring · uuid

source_job_statusstring

missingarray · required

Nested fields

string · webm, hevc

variantsobject · required

400 Invalid input

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Authentication required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Write key required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Resource not found in credential workspace

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Revision conflict or retained history

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

422 Required release media unavailable

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "operationId": "getProjectCanvasStatus",
  "tags": [
    "Canvases"
  ],
  "summary": "Read canvas generation progress",
  "description": "Generation progress for a canvas. Poll it every 15 to 30 seconds after `POST /v1/canvases/{canvasId}/generate-all`. Read-only keys can call it, and it never changes the canvas. `status.generation.nodes` and `status.generation.edges` count total, completed, pending and failed parts. Pending means neither finished nor failed. Stop polling when `status.generation.ready` is true: every node image and edge video exists. The canvas plays in the editor once `status.preview.ready` is also true. If `status.preview.waiting_edges` is above 0, keep polling because derivatives are still being prepared. If `status.preview.repairable` is true, call `POST /v1/canvases/{canvasId}/repair` with `dry_run: true` first. If any `failed` count is above 0, read `status.failed_nodes` and `status.failed_edges`. Each entry has the part id, its `job_id` and a customer-safe `error`. A retry is a new paid attempt, so ask before retrying. Returns 409 when the canvas has no mascot generation context.",
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "canvasId",
      "in": "path"
    }
  ],
  "responses": {
    "200": {
      "description": "Successful response",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "object": {
                    "type": "string",
                    "enum": [
                      "canvas_status"
                    ]
                  },
                  "canvas_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "graph_content_hash": {
                    "type": "string"
                  },
                  "status": {
                    "type": "object",
                    "properties": {
                      "generation": {
                        "type": "object",
                        "properties": {
                          "ready": {
                            "type": "boolean"
                          },
                          "nodes": {
                            "type": "object",
                            "properties": {
                              "total": {
                                "type": "number"
                              },
                              "completed": {
                                "type": "number"
                              },
                              "pending": {
                                "type": "number",
                                "description": "Incomplete node count. Includes failed nodes for backward compatibility; inspect failed for the terminal subset."
                              },
                              "failed": {
                                "type": "number"
                              }
                            },
                            "required": [
                              "total",
                              "completed",
                              "pending",
                              "failed"
                            ]
                          },
                          "edges": {
                            "type": "object",
                            "properties": {
                              "total": {
                                "type": "number"
                              },
                              "completed": {
                                "type": "number"
                              },
                              "pending": {
                                "type": "number"
                              },
                              "failed": {
                                "type": "number"
                              }
                            },
                            "required": [
                              "total",
                              "completed",
                              "pending",
                              "failed"
                            ]
                          }
                        },
                        "required": [
                          "ready",
                          "nodes",
                          "edges"
                        ]
                      },
                      "preview": {
                        "type": "object",
                        "properties": {
                          "ready": {
                            "type": "boolean"
                          },
                          "repairable": {
                            "type": "boolean"
                          },
                          "repairable_edges": {
                            "type": "number"
                          },
                          "waiting_edges": {
                            "type": "number"
                          },
                          "missing_edges": {
                            "type": "number"
                          },
                          "missing_formats": {
                            "type": "array",
                            "items": {
                              "type": "string",
                              "enum": [
                                "webm",
                                "hevc"
                              ]
                            }
                          }
                        },
                        "required": [
                          "ready",
                          "repairable",
                          "repairable_edges",
                          "waiting_edges",
                          "missing_edges",
                          "missing_formats"
                        ]
                      },
                      "variants": {
                        "type": "object",
                        "properties": {
                          "sizes": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "missing": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "edge_id": {
                                  "type": "string"
                                },
                                "size": {
                                  "type": "string"
                                },
                                "formats": {
                                  "type": "array",
                                  "items": {
                                    "type": "string",
                                    "enum": [
                                      "webm",
                                      "hevc"
                                    ]
                                  }
                                }
                              },
                              "required": [
                                "edge_id",
                                "size",
                                "formats"
                              ]
                            }
                          }
                        },
                        "required": [
                          "sizes",
                          "missing"
                        ]
                      },
                      "failed_nodes": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "properties": {
                            "node_id": {
                              "type": "string"
                            },
                            "job_id": {
                              "type": "string",
                              "nullable": true,
                              "format": "uuid"
                            },
                            "error": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "node_id",
                            "job_id",
                            "error"
                          ]
                        }
                      },
                      "failed_edges": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "properties": {
                            "edge_id": {
                              "type": "string"
                            },
                            "job_id": {
                              "type": "string",
                              "nullable": true,
                              "format": "uuid"
                            },
                            "error": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "edge_id",
                            "job_id",
                            "error"
                          ]
                        }
                      },
                      "edge_media": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "properties": {
                            "edge_id": {
                              "type": "string"
                            },
                            "source": {
                              "type": "string"
                            },
                            "target": {
                              "type": "string"
                            },
                            "video_asset_id": {
                              "type": "string",
                              "nullable": true,
                              "format": "uuid"
                            },
                            "base": {
                              "type": "object",
                              "properties": {
                                "video_ready": {
                                  "type": "boolean"
                                },
                                "webm_ready": {
                                  "type": "boolean"
                                },
                                "hevc_ready": {
                                  "type": "boolean"
                                },
                                "preview_ready": {
                                  "type": "boolean"
                                },
                                "derivatives_in_flight": {
                                  "type": "boolean"
                                },
                                "source_job_id": {
                                  "type": "string",
                                  "format": "uuid"
                                },
                                "source_job_status": {
                                  "type": "string"
                                },
                                "missing": {
                                  "type": "array",
                                  "items": {
                                    "type": "string",
                                    "enum": [
                                      "webm",
                                      "hevc"
                                    ]
                                  }
                                }
                              },
                              "required": [
                                "video_ready",
                                "webm_ready",
                                "hevc_ready",
                                "preview_ready",
                                "derivatives_in_flight",
                                "missing"
                              ]
                            },
                            "variants": {
                              "type": "object",
                              "additionalProperties": {
                                "type": "object",
                                "properties": {
                                  "webm_ready": {
                                    "type": "boolean"
                                  },
                                  "hevc_ready": {
                                    "type": "boolean"
                                  },
                                  "missing": {
                                    "type": "array",
                                    "items": {
                                      "type": "string",
                                      "enum": [
                                        "webm",
                                        "hevc"
                                      ]
                                    }
                                  }
                                },
                                "required": [
                                  "webm_ready",
                                  "hevc_ready",
                                  "missing"
                                ]
                              }
                            }
                          },
                          "required": [
                            "edge_id",
                            "source",
                            "target",
                            "video_asset_id",
                            "base",
                            "variants"
                          ]
                        }
                      }
                    },
                    "required": [
                      "generation",
                      "preview",
                      "variants",
                      "failed_nodes",
                      "failed_edges"
                    ]
                  }
                },
                "required": [
                  "object",
                  "canvas_id",
                  "graph_content_hash",
                  "status"
                ]
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Invalid input",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "401": {
      "description": "Authentication required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "403": {
      "description": "Write key required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "404": {
      "description": "Resource not found in credential workspace",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "409": {
      "description": "Revision conflict or retained history",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "422": {
      "description": "Required release media unavailable",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  },
  "x-masko-api-version": "2026-09-26"
}

GET/v1/canvases/{canvasId}/historyRead draft, named checkpoints and immutable releases

Returns the current draft, named checkpoints and immutable releases of a canvas.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

canvasIdpath · required

string

Responses

200 Successful response

application/json

dataobject · required

Nested fields

draftobject · required

Nested fields

objectstring · required

Values: "canvas"

idstring · uuid · required

project_idstring · uuid · nullable · required

mascot_idstring · uuid · nullable · required

namestring · required

graphobject · nullable · required

graph_content_hashstring · required

created_atstring · nullable · required

updated_atstring · nullable · required

checkpointsarray · required

Nested fields

idstring · uuid · required

canvas_idstring · uuid · required

namestring · required

graphobject · required

graph_content_hashstring · required

created_bystring · uuid · required

created_atstring · required

releasesarray · required

Nested fields

idstring · uuid · required

canvas_idstring · uuid · required

numberinteger · required

notesstring · required

mascot_version_idstring · uuid · required

created_bystring · uuid · required

created_atstring · required

400 Invalid input

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Authentication required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Write key required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Resource not found in credential workspace

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Revision conflict or retained history

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

422 Required release media unavailable

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "operationId": "getCanvasHistory",
  "tags": [
    "Canvases"
  ],
  "summary": "Read draft, named checkpoints and immutable releases",
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "canvasId",
      "in": "path"
    }
  ],
  "responses": {
    "200": {
      "description": "Successful response",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "draft": {
                    "type": "object",
                    "properties": {
                      "object": {
                        "type": "string",
                        "enum": [
                          "canvas"
                        ]
                      },
                      "id": {
                        "type": "string",
                        "format": "uuid"
                      },
                      "project_id": {
                        "type": "string",
                        "nullable": true,
                        "format": "uuid"
                      },
                      "mascot_id": {
                        "type": "string",
                        "nullable": true,
                        "format": "uuid"
                      },
                      "name": {
                        "type": "string"
                      },
                      "graph": {
                        "type": "object",
                        "nullable": true,
                        "additionalProperties": {
                          "nullable": true
                        }
                      },
                      "graph_content_hash": {
                        "type": "string"
                      },
                      "created_at": {
                        "type": "string",
                        "nullable": true
                      },
                      "updated_at": {
                        "type": "string",
                        "nullable": true
                      }
                    },
                    "required": [
                      "object",
                      "id",
                      "project_id",
                      "mascot_id",
                      "name",
                      "graph",
                      "graph_content_hash",
                      "created_at",
                      "updated_at"
                    ]
                  },
                  "checkpoints": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "canvas_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "name": {
                          "type": "string"
                        },
                        "graph": {
                          "type": "object",
                          "additionalProperties": {
                            "nullable": true
                          }
                        },
                        "graph_content_hash": {
                          "type": "string"
                        },
                        "created_by": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "created_at": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "id",
                        "canvas_id",
                        "name",
                        "graph",
                        "graph_content_hash",
                        "created_by",
                        "created_at"
                      ]
                    }
                  },
                  "releases": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "canvas_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "number": {
                          "type": "integer"
                        },
                        "notes": {
                          "type": "string"
                        },
                        "mascot_version_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "created_by": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "created_at": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "id",
                        "canvas_id",
                        "number",
                        "notes",
                        "mascot_version_id",
                        "created_by",
                        "created_at"
                      ],
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  }
                },
                "required": [
                  "draft",
                  "checkpoints",
                  "releases"
                ]
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Invalid input",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "401": {
      "description": "Authentication required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "403": {
      "description": "Write key required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "404": {
      "description": "Resource not found in credential workspace",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "409": {
      "description": "Revision conflict or retained history",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "422": {
      "description": "Required release media unavailable",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  },
  "description": "Returns the current draft, named checkpoints and immutable releases of a canvas.",
  "x-masko-api-version": "2026-09-26"
}

POST/v1/canvases/{canvasId}/historySave a checkpoint, restore as draft, or create a release

Restore atomically checkpoints current work first. No generation is run. A release requires complete media and does not activate Desktop or publish a listing. A release the Masko player would not play (a condition it cannot read, an input without a starting value, a pose without a picture) is refused with 422 naming what to fix.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

canvasIdpath · required

string

Idempotency-Keyheader

string

Request body

application/json

Option 1

actionstring · required

Values: "checkpoint"

namestring · required

Length: 1 to 120 characters

expected_graph_hashstring · required

Length: 1 to unbounded characters

Option 2

actionstring · required

Values: "restore"

checkpoint_idstring · uuid · required

expected_graph_hashstring · required

Length: 1 to unbounded characters

Option 3

actionstring · required

Values: "restore_release"

release_idstring · uuid · required

expected_graph_hashstring · required

Length: 1 to unbounded characters

Option 4

actionstring · required

Values: "copy_release"

release_idstring · uuid · required

namestring · required

Length: 1 to 120 characters

expected_graph_hashstring · required

Length: 1 to unbounded characters

Option 5

actionstring · required

Values: "release"

notesstring

Default: ""

Length: 0 to 4000 characters

operation_idstring · uuid · required

expected_graph_hashstring · required

Length: 1 to unbounded characters

Responses

200 Successful response

application/json

dataobject · required

Nested fields

Option 1

idstring · uuid · required

canvas_idstring · uuid · required

namestring · required

graphobject · required

graph_content_hashstring · required

created_bystring · uuid · required

created_atstring · required

Option 2

idstring · uuid · required

canvas_idstring · uuid · required

numberinteger · required

notesstring · required

mascot_version_idstring · uuid · required

created_bystring · uuid · required

created_atstring · required

Option 3

objectstring · required

Values: "canvas"

idstring · uuid · required

project_idstring · uuid · nullable · required

mascot_idstring · uuid · nullable · required

namestring · required

graphobject · nullable · required

graph_content_hashstring · required

created_atstring · nullable · required

updated_atstring · nullable · required

400 Invalid input

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Authentication required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Write key required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Resource not found in credential workspace

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Revision conflict or retained history

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

422 Required release media unavailable

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "operationId": "changeCanvasHistory",
  "tags": [
    "Canvases"
  ],
  "summary": "Save a checkpoint, restore as draft, or create a release",
  "description": "Restore atomically checkpoints current work first. No generation is run. A release requires complete media and does not activate Desktop or publish a listing. A release the Masko player would not play (a condition it cannot read, an input without a starting value, a pose without a picture) is refused with 422 naming what to fix.",
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "canvasId",
      "in": "path"
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.",
      "schema": {
        "type": "string",
        "maxLength": 255
      }
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "oneOf": [
            {
              "type": "object",
              "properties": {
                "action": {
                  "type": "string",
                  "enum": [
                    "checkpoint"
                  ]
                },
                "name": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 120
                },
                "expected_graph_hash": {
                  "type": "string",
                  "minLength": 1
                }
              },
              "required": [
                "action",
                "name",
                "expected_graph_hash"
              ],
              "additionalProperties": false
            },
            {
              "type": "object",
              "properties": {
                "action": {
                  "type": "string",
                  "enum": [
                    "restore"
                  ]
                },
                "checkpoint_id": {
                  "type": "string",
                  "format": "uuid"
                },
                "expected_graph_hash": {
                  "type": "string",
                  "minLength": 1
                }
              },
              "required": [
                "action",
                "checkpoint_id",
                "expected_graph_hash"
              ],
              "additionalProperties": false
            },
            {
              "type": "object",
              "properties": {
                "action": {
                  "type": "string",
                  "enum": [
                    "restore_release"
                  ]
                },
                "release_id": {
                  "type": "string",
                  "format": "uuid"
                },
                "expected_graph_hash": {
                  "type": "string",
                  "minLength": 1
                }
              },
              "required": [
                "action",
                "release_id",
                "expected_graph_hash"
              ],
              "additionalProperties": false
            },
            {
              "type": "object",
              "properties": {
                "action": {
                  "type": "string",
                  "enum": [
                    "copy_release"
                  ]
                },
                "release_id": {
                  "type": "string",
                  "format": "uuid"
                },
                "name": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 120
                },
                "expected_graph_hash": {
                  "type": "string",
                  "minLength": 1
                }
              },
              "required": [
                "action",
                "release_id",
                "name",
                "expected_graph_hash"
              ],
              "additionalProperties": false
            },
            {
              "type": "object",
              "properties": {
                "action": {
                  "type": "string",
                  "enum": [
                    "release"
                  ]
                },
                "notes": {
                  "type": "string",
                  "maxLength": 4000,
                  "default": ""
                },
                "operation_id": {
                  "type": "string",
                  "format": "uuid"
                },
                "expected_graph_hash": {
                  "type": "string",
                  "minLength": 1
                }
              },
              "required": [
                "action",
                "operation_id",
                "expected_graph_hash"
              ],
              "additionalProperties": false
            }
          ]
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Successful response",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string",
                        "format": "uuid"
                      },
                      "canvas_id": {
                        "type": "string",
                        "format": "uuid"
                      },
                      "name": {
                        "type": "string"
                      },
                      "graph": {
                        "type": "object",
                        "additionalProperties": {
                          "nullable": true
                        }
                      },
                      "graph_content_hash": {
                        "type": "string"
                      },
                      "created_by": {
                        "type": "string",
                        "format": "uuid"
                      },
                      "created_at": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "id",
                      "canvas_id",
                      "name",
                      "graph",
                      "graph_content_hash",
                      "created_by",
                      "created_at"
                    ]
                  },
                  {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string",
                        "format": "uuid"
                      },
                      "canvas_id": {
                        "type": "string",
                        "format": "uuid"
                      },
                      "number": {
                        "type": "integer"
                      },
                      "notes": {
                        "type": "string"
                      },
                      "mascot_version_id": {
                        "type": "string",
                        "format": "uuid"
                      },
                      "created_by": {
                        "type": "string",
                        "format": "uuid"
                      },
                      "created_at": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "id",
                      "canvas_id",
                      "number",
                      "notes",
                      "mascot_version_id",
                      "created_by",
                      "created_at"
                    ],
                    "additionalProperties": {
                      "nullable": true
                    }
                  },
                  {
                    "type": "object",
                    "properties": {
                      "object": {
                        "type": "string",
                        "enum": [
                          "canvas"
                        ]
                      },
                      "id": {
                        "type": "string",
                        "format": "uuid"
                      },
                      "project_id": {
                        "type": "string",
                        "nullable": true,
                        "format": "uuid"
                      },
                      "mascot_id": {
                        "type": "string",
                        "nullable": true,
                        "format": "uuid"
                      },
                      "name": {
                        "type": "string"
                      },
                      "graph": {
                        "type": "object",
                        "nullable": true,
                        "additionalProperties": {
                          "nullable": true
                        }
                      },
                      "graph_content_hash": {
                        "type": "string"
                      },
                      "created_at": {
                        "type": "string",
                        "nullable": true
                      },
                      "updated_at": {
                        "type": "string",
                        "nullable": true
                      }
                    },
                    "required": [
                      "object",
                      "id",
                      "project_id",
                      "mascot_id",
                      "name",
                      "graph",
                      "graph_content_hash",
                      "created_at",
                      "updated_at"
                    ]
                  }
                ]
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Invalid input",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "401": {
      "description": "Authentication required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "403": {
      "description": "Write key required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "404": {
      "description": "Resource not found in credential workspace",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "409": {
      "description": "Revision conflict or retained history",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "422": {
      "description": "Required release media unavailable",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  },
  "x-masko-api-version": "2026-09-26"
}

GET/v1/mascots/{id}/publicationRead selected customer publication and review status

Customer publication is separate from CDN hosting. GET state is null until action:start. state.visibility (unpublished/published/archived) is independent of state.changes_status (draft/pending/approved/rejected). save_draft requires the current draft_id and accepts incomplete listing details. Preview and submit require an editable draft; all submissions, including admin submissions, enter pending review. The project workspace owns the seller identity. GET includes seller with exactly one of user_id or organization_id and can_publish (whether this viewer may manage publication). Team owners/admins manage publishing; submission also retains the existing creator eligibility requirement. A team listing uses the team profile and credits earnings to the team wallet. The submitting member is recorded separately. Marketplace submissions require a handle on the selling workspace profile. Approval and restore enforce this rule, and a creator cannot make their profile private or unlisted while a library is published. Pending changes leave approved media, price and description unchanged. Approval atomically replaces the selected content; rejection preserves the draft and approved version. archive stops new acquisition; restore republishes only the approved version. Archiving during review prevents approval from making the listing visible. Submitting while archived requests publication after approval. remove stages a draft change and never modifies the live listing directly. Existing buyers retain acquired content. Preview returns plan_id, valid for ten minutes. Submit requires that plan and fails with 409 if source context or dependencies changed. Review uses the frozen submission. Removing discovery preserves retained uses. Marketplace offers require at least one generated image on the mascot and a selection containing at least one image and five animations. Optional offer.cover_asset_id selects an included gallery image as the listing thumbnail; videos and exports are rejected. If omitted, an included generated image is preferred automatically, otherwise the first included image. Include at least one image. The mascot name is frozen at submission and changes publicly only after approval; display names need not be unique. Delivery formats are grouped under gallery assets; GET includes signed transparent_url, webm_url and hevc_url when available, plus has_generated_image. Mac version: selection.player_canvas_id names a canvas of this mascot that plays on Masko for Mac. Preview and submit freeze its graph into snapshot.player (canvas_id, name, graph, graph_hash) and include every image and animation it uses as selected content. The graph must validate and its animations must be generated source clips. Without player_canvas_id, the approved Mac version carries forward; removing any of its media returns 409. A mascot's first Marketplace offer requires a Mac version (409 otherwise). GET includes player (approved Mac version, whether one is required, and the mascot's canvases with counts and any blocking issue), and listing_preview.player.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

Responses

200 Successful response

application/json

dataobject · required

Nested fields

ownerboolean · required

Values: true

sellerobject · required

Nested fields

Option 1

user_idstring · uuid · required

organization_idobject · nullable · required

can_publishboolean · required

Option 2

user_idobject · nullable · required

organization_idstring · uuid · required

can_publishboolean · required

400 Invalid input

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Authentication required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Write key required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Resource not found in credential workspace

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Revision conflict or retained history

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

422 Required release media unavailable

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "operationId": "getMascotPublication",
  "tags": [
    "Mascots"
  ],
  "summary": "Read selected customer publication and review status",
  "description": "Customer publication is separate from CDN hosting. GET state is null until action:start. state.visibility (unpublished/published/archived) is independent of state.changes_status (draft/pending/approved/rejected). save_draft requires the current draft_id and accepts incomplete listing details. Preview and submit require an editable draft; all submissions, including admin submissions, enter pending review. The project workspace owns the seller identity. GET includes seller with exactly one of user_id or organization_id and can_publish (whether this viewer may manage publication). Team owners/admins manage publishing; submission also retains the existing creator eligibility requirement. A team listing uses the team profile and credits earnings to the team wallet. The submitting member is recorded separately. Marketplace submissions require a handle on the selling workspace profile. Approval and restore enforce this rule, and a creator cannot make their profile private or unlisted while a library is published. Pending changes leave approved media, price and description unchanged. Approval atomically replaces the selected content; rejection preserves the draft and approved version. archive stops new acquisition; restore republishes only the approved version. Archiving during review prevents approval from making the listing visible. Submitting while archived requests publication after approval. remove stages a draft change and never modifies the live listing directly. Existing buyers retain acquired content. Preview returns plan_id, valid for ten minutes. Submit requires that plan and fails with 409 if source context or dependencies changed. Review uses the frozen submission. Removing discovery preserves retained uses. Marketplace offers require at least one generated image on the mascot and a selection containing at least one image and five animations. Optional offer.cover_asset_id selects an included gallery image as the listing thumbnail; videos and exports are rejected. If omitted, an included generated image is preferred automatically, otherwise the first included image. Include at least one image. The mascot name is frozen at submission and changes publicly only after approval; display names need not be unique. Delivery formats are grouped under gallery assets; GET includes signed transparent_url, webm_url and hevc_url when available, plus has_generated_image. Mac version: selection.player_canvas_id names a canvas of this mascot that plays on Masko for Mac. Preview and submit freeze its graph into snapshot.player (canvas_id, name, graph, graph_hash) and include every image and animation it uses as selected content. The graph must validate and its animations must be generated source clips. Without player_canvas_id, the approved Mac version carries forward; removing any of its media returns 409. A mascot's first Marketplace offer requires a Mac version (409 otherwise). GET includes player (approved Mac version, whether one is required, and the mascot's canvases with counts and any blocking issue), and listing_preview.player.",
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    }
  ],
  "responses": {
    "200": {
      "description": "Successful response",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "owner": {
                    "type": "boolean",
                    "enum": [
                      true
                    ]
                  },
                  "seller": {
                    "anyOf": [
                      {
                        "type": "object",
                        "properties": {
                          "user_id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "organization_id": {
                            "nullable": true
                          },
                          "can_publish": {
                            "type": "boolean"
                          }
                        },
                        "required": [
                          "user_id",
                          "organization_id",
                          "can_publish"
                        ],
                        "additionalProperties": false
                      },
                      {
                        "type": "object",
                        "properties": {
                          "user_id": {
                            "nullable": true
                          },
                          "organization_id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "can_publish": {
                            "type": "boolean"
                          }
                        },
                        "required": [
                          "user_id",
                          "organization_id",
                          "can_publish"
                        ],
                        "additionalProperties": false
                      }
                    ]
                  }
                },
                "required": [
                  "owner",
                  "seller"
                ],
                "additionalProperties": {
                  "nullable": true
                }
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Invalid input",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "401": {
      "description": "Authentication required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "403": {
      "description": "Write key required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "404": {
      "description": "Resource not found in credential workspace",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "409": {
      "description": "Revision conflict or retained history",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "422": {
      "description": "Required release media unavailable",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  },
  "x-masko-api-version": "2026-09-26"
}

POST/v1/mascots/{id}/publicationStart, edit, review, archive or restore a mascot listing

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

Idempotency-Keyheader

string

Request body

application/json

Option 1

actionstring · required

Values: "start"

Option 2

actionstring · required

Values: "save_draft"

draft_idstring · uuid · required

selectionobject · required

Nested fields

asset_idsarray · required

Items: 0 to 500

Nested fields

string

identity_idsarray · required

Items: 0 to 100

Nested fields

string

asset_identity_idsobject

player_canvas_idstring · uuid

Canvas of this mascot that plays on Masko for Mac. Its graph is frozen into the submission and every image and animation it uses is included automatically. Omit it to keep the approved Mac version, which requires that all of its media stay selected. A mascot's first Marketplace offer needs one.

offerobject

Nested fields

cover_asset_idstring · uuid

Included image used as the listing thumbnail; animations and exports are not supported.

price_creditsinteger · required

Range: 0 to 100000

descriptionstring · required

Length: 0 to 2000 characters

accept_creator_termsboolean

Option 3

actionstring · required

Values: "archive"

Option 4

actionstring · required

Values: "restore"

Option 5

actionstring · required

Values: "withdraw"

Option 6

actionstring · required

Values: "preview"

selectionobject · required

Nested fields

asset_idsarray · required

Items: 0 to 500

Nested fields

string

identity_idsarray · required

Items: 0 to 100

Nested fields

string

asset_identity_idsobject

player_canvas_idstring · uuid

offerobject

Nested fields

cover_asset_idstring · uuid

Included image used as the listing thumbnail; animations and exports are not supported.

price_creditsinteger · required

Range: 0 to 100000

descriptionstring

Length: 0 to 2000 characters

accept_creator_termsboolean · required

Values: true

Option 7

actionstring · required

Values: "submit"

selectionobject · required

Nested fields

asset_idsarray · required

Items: 0 to 500

Nested fields

string

identity_idsarray · required

Items: 0 to 100

Nested fields

string

asset_identity_idsobject

player_canvas_idstring · uuid

offerobject

Nested fields

cover_asset_idstring · uuid

Included image used as the listing thumbnail; animations and exports are not supported.

price_creditsinteger · required

Range: 0 to 100000

descriptionstring

Length: 0 to 2000 characters

accept_creator_termsboolean · required

Values: true

plan_idstring · uuid · required

Option 8

actionstring · required

Values: "remove"

kindstring · required

Values: "identity", "asset"

resource_idstring · required

Length: 1 to unbounded characters

Option 9

actionstring · required

Values: "duplicate"

variantobject · required

Nested fields

identity_idstring · required

Length: 1 to unbounded characters

project_idstring · uuid · required

namestring · required

Length: 1 to 100 characters

Responses

200 Successful response

application/json

dataobject · required

400 Invalid input

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Authentication required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Write key required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Resource not found in credential workspace

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Revision conflict or retained history

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

422 Required release media unavailable

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "operationId": "changeMascotPublication",
  "tags": [
    "Mascots"
  ],
  "summary": "Start, edit, review, archive or restore a mascot listing",
  "description": "Customer publication is separate from CDN hosting. GET state is null until action:start. state.visibility (unpublished/published/archived) is independent of state.changes_status (draft/pending/approved/rejected). save_draft requires the current draft_id and accepts incomplete listing details. Preview and submit require an editable draft; all submissions, including admin submissions, enter pending review. The project workspace owns the seller identity. GET includes seller with exactly one of user_id or organization_id and can_publish (whether this viewer may manage publication). Team owners/admins manage publishing; submission also retains the existing creator eligibility requirement. A team listing uses the team profile and credits earnings to the team wallet. The submitting member is recorded separately. Marketplace submissions require a handle on the selling workspace profile. Approval and restore enforce this rule, and a creator cannot make their profile private or unlisted while a library is published. Pending changes leave approved media, price and description unchanged. Approval atomically replaces the selected content; rejection preserves the draft and approved version. archive stops new acquisition; restore republishes only the approved version. Archiving during review prevents approval from making the listing visible. Submitting while archived requests publication after approval. remove stages a draft change and never modifies the live listing directly. Existing buyers retain acquired content. Preview returns plan_id, valid for ten minutes. Submit requires that plan and fails with 409 if source context or dependencies changed. Review uses the frozen submission. Removing discovery preserves retained uses. Marketplace offers require at least one generated image on the mascot and a selection containing at least one image and five animations. Optional offer.cover_asset_id selects an included gallery image as the listing thumbnail; videos and exports are rejected. If omitted, an included generated image is preferred automatically, otherwise the first included image. Include at least one image. The mascot name is frozen at submission and changes publicly only after approval; display names need not be unique. Delivery formats are grouped under gallery assets; GET includes signed transparent_url, webm_url and hevc_url when available, plus has_generated_image. Mac version: selection.player_canvas_id names a canvas of this mascot that plays on Masko for Mac. Preview and submit freeze its graph into snapshot.player (canvas_id, name, graph, graph_hash) and include every image and animation it uses as selected content. The graph must validate and its animations must be generated source clips. Without player_canvas_id, the approved Mac version carries forward; removing any of its media returns 409. A mascot's first Marketplace offer requires a Mac version (409 otherwise). GET includes player (approved Mac version, whether one is required, and the mascot's canvases with counts and any blocking issue), and listing_preview.player.",
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.",
      "schema": {
        "type": "string",
        "maxLength": 255
      }
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "oneOf": [
            {
              "type": "object",
              "properties": {
                "action": {
                  "type": "string",
                  "enum": [
                    "start"
                  ]
                }
              },
              "required": [
                "action"
              ],
              "additionalProperties": false
            },
            {
              "type": "object",
              "properties": {
                "action": {
                  "type": "string",
                  "enum": [
                    "save_draft"
                  ]
                },
                "draft_id": {
                  "type": "string",
                  "format": "uuid"
                },
                "selection": {
                  "type": "object",
                  "properties": {
                    "asset_ids": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "format": "uuid"
                      },
                      "maxItems": 500
                    },
                    "identity_ids": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "minLength": 1
                      },
                      "maxItems": 100
                    },
                    "asset_identity_ids": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "array",
                        "items": {
                          "type": "string",
                          "minLength": 1
                        },
                        "minItems": 1,
                        "maxItems": 2
                      }
                    },
                    "player_canvas_id": {
                      "type": "string",
                      "format": "uuid",
                      "description": "Canvas of this mascot that plays on Masko for Mac. Its graph is frozen into the submission and every image and animation it uses is included automatically. Omit it to keep the approved Mac version, which requires that all of its media stay selected. A mascot's first Marketplace offer needs one."
                    },
                    "offer": {
                      "type": "object",
                      "properties": {
                        "cover_asset_id": {
                          "type": "string",
                          "format": "uuid",
                          "description": "Included image used as the listing thumbnail; animations and exports are not supported."
                        },
                        "price_credits": {
                          "type": "integer",
                          "minimum": 0,
                          "maximum": 100000
                        },
                        "description": {
                          "type": "string",
                          "maxLength": 2000
                        },
                        "accept_creator_terms": {
                          "type": "boolean"
                        }
                      },
                      "required": [
                        "price_credits",
                        "description"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "asset_ids",
                    "identity_ids"
                  ],
                  "additionalProperties": false
                }
              },
              "required": [
                "action",
                "draft_id",
                "selection"
              ],
              "additionalProperties": false
            },
            {
              "type": "object",
              "properties": {
                "action": {
                  "type": "string",
                  "enum": [
                    "archive"
                  ]
                }
              },
              "required": [
                "action"
              ],
              "additionalProperties": false
            },
            {
              "type": "object",
              "properties": {
                "action": {
                  "type": "string",
                  "enum": [
                    "restore"
                  ]
                }
              },
              "required": [
                "action"
              ],
              "additionalProperties": false
            },
            {
              "type": "object",
              "properties": {
                "action": {
                  "type": "string",
                  "enum": [
                    "withdraw"
                  ]
                }
              },
              "required": [
                "action"
              ],
              "additionalProperties": false
            },
            {
              "type": "object",
              "properties": {
                "action": {
                  "type": "string",
                  "enum": [
                    "preview"
                  ]
                },
                "selection": {
                  "type": "object",
                  "properties": {
                    "asset_ids": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "format": "uuid"
                      },
                      "maxItems": 500
                    },
                    "identity_ids": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "minLength": 1
                      },
                      "maxItems": 100
                    },
                    "asset_identity_ids": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "array",
                        "items": {
                          "type": "string",
                          "minLength": 1
                        },
                        "minItems": 1,
                        "maxItems": 2
                      }
                    },
                    "player_canvas_id": {
                      "type": "string",
                      "format": "uuid",
                      "description": "Canvas of this mascot that plays on Masko for Mac. Its graph is frozen into the submission and every image and animation it uses is included automatically. Omit it to keep the approved Mac version, which requires that all of its media stay selected. A mascot's first Marketplace offer needs one."
                    },
                    "offer": {
                      "type": "object",
                      "properties": {
                        "cover_asset_id": {
                          "type": "string",
                          "format": "uuid",
                          "description": "Included image used as the listing thumbnail; animations and exports are not supported."
                        },
                        "price_credits": {
                          "type": "integer",
                          "minimum": 0,
                          "maximum": 100000
                        },
                        "description": {
                          "type": "string",
                          "maxLength": 2000
                        },
                        "accept_creator_terms": {
                          "type": "boolean",
                          "enum": [
                            true
                          ]
                        }
                      },
                      "required": [
                        "price_credits",
                        "accept_creator_terms"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "asset_ids",
                    "identity_ids"
                  ],
                  "additionalProperties": false
                }
              },
              "required": [
                "action",
                "selection"
              ],
              "additionalProperties": false
            },
            {
              "type": "object",
              "properties": {
                "action": {
                  "type": "string",
                  "enum": [
                    "submit"
                  ]
                },
                "selection": {
                  "type": "object",
                  "properties": {
                    "asset_ids": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "format": "uuid"
                      },
                      "maxItems": 500
                    },
                    "identity_ids": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "minLength": 1
                      },
                      "maxItems": 100
                    },
                    "asset_identity_ids": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "array",
                        "items": {
                          "type": "string",
                          "minLength": 1
                        },
                        "minItems": 1,
                        "maxItems": 2
                      }
                    },
                    "player_canvas_id": {
                      "type": "string",
                      "format": "uuid",
                      "description": "Canvas of this mascot that plays on Masko for Mac. Its graph is frozen into the submission and every image and animation it uses is included automatically. Omit it to keep the approved Mac version, which requires that all of its media stay selected. A mascot's first Marketplace offer needs one."
                    },
                    "offer": {
                      "type": "object",
                      "properties": {
                        "cover_asset_id": {
                          "type": "string",
                          "format": "uuid",
                          "description": "Included image used as the listing thumbnail; animations and exports are not supported."
                        },
                        "price_credits": {
                          "type": "integer",
                          "minimum": 0,
                          "maximum": 100000
                        },
                        "description": {
                          "type": "string",
                          "maxLength": 2000
                        },
                        "accept_creator_terms": {
                          "type": "boolean",
                          "enum": [
                            true
                          ]
                        }
                      },
                      "required": [
                        "price_credits",
                        "accept_creator_terms"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "asset_ids",
                    "identity_ids"
                  ],
                  "additionalProperties": false
                },
                "plan_id": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "required": [
                "action",
                "selection",
                "plan_id"
              ],
              "additionalProperties": false
            },
            {
              "type": "object",
              "properties": {
                "action": {
                  "type": "string",
                  "enum": [
                    "remove"
                  ]
                },
                "kind": {
                  "type": "string",
                  "enum": [
                    "identity",
                    "asset"
                  ]
                },
                "resource_id": {
                  "type": "string",
                  "minLength": 1
                }
              },
              "required": [
                "action",
                "kind",
                "resource_id"
              ],
              "additionalProperties": false
            },
            {
              "type": "object",
              "properties": {
                "action": {
                  "type": "string",
                  "enum": [
                    "duplicate"
                  ]
                },
                "variant": {
                  "type": "object",
                  "properties": {
                    "identity_id": {
                      "type": "string",
                      "minLength": 1
                    },
                    "project_id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "name": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 100
                    }
                  },
                  "required": [
                    "identity_id",
                    "project_id",
                    "name"
                  ],
                  "additionalProperties": false
                }
              },
              "required": [
                "action",
                "variant"
              ],
              "additionalProperties": false
            }
          ]
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Successful response",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "additionalProperties": {
                  "nullable": true
                }
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Invalid input",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "401": {
      "description": "Authentication required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "403": {
      "description": "Write key required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "404": {
      "description": "Resource not found in credential workspace",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "409": {
      "description": "Revision conflict or retained history",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "422": {
      "description": "Required release media unavailable",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  },
  "x-masko-api-version": "2026-09-26"
}

POST/v1/mascots/{id}/variants/duplicateCopy Original or a variant without generation or a canvas

Copies the Original appearance or a variant into a new variant without generating anything and without a canvas.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

Idempotency-Keyheader

string

Request body

application/json

identity_idstring · required

Length: 1 to unbounded characters

project_idstring · uuid · required

namestring · required

Length: 1 to 80 characters

Responses

200 Successful response

application/json

dataobject · required

400 Invalid input

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Authentication required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Write key required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Resource not found in credential workspace

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Revision conflict or retained history

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

422 Required release media unavailable

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "operationId": "duplicateMascotIdentity",
  "tags": [
    "Mascots"
  ],
  "summary": "Copy Original or a variant without generation or a canvas",
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.",
      "schema": {
        "type": "string",
        "maxLength": 255
      }
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "identity_id": {
              "type": "string",
              "minLength": 1
            },
            "project_id": {
              "type": "string",
              "format": "uuid"
            },
            "name": {
              "type": "string",
              "minLength": 1,
              "maxLength": 80
            }
          },
          "required": [
            "identity_id",
            "project_id",
            "name"
          ],
          "additionalProperties": false
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Successful response",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "additionalProperties": {
                  "nullable": true
                }
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Invalid input",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "401": {
      "description": "Authentication required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "403": {
      "description": "Write key required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "404": {
      "description": "Resource not found in credential workspace",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "409": {
      "description": "Revision conflict or retained history",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "422": {
      "description": "Required release media unavailable",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  },
  "description": "Copies the Original appearance or a variant into a new variant without generating anything and without a canvas.",
  "x-masko-api-version": "2026-09-26"
}

GET/v1/canvases/{canvasId}/releases/{releaseId}/deliveryGet signed playback media for one immutable release

Call from your backend with its API key and forward only delivery to website visitors. This response contains no authoring credentials, generation context or private identity references. Creating a release does not activate it.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

canvasIdpath · required

string

releaseIdpath · required

string

targetquery

web returns WebM and HEVC links, apple returns HEVC links for iPhone, iPad and Mac players, android returns stacked MP4 links for Android players, desktop returns the full media set.

string · web, apple, android, desktop

formatsquery

Comma-separated formats the player plays beyond its target's own. With av1 and target apple or android, every clip that has a stacked AV1 file returns it as videos.av1 in place of hevc or stacked: colour above, transparency below, 2 to 3 times lighter at the same look. The Masko player gives the value to send as MaskoPlayer.formats. Other targets ignore it.

string

Responses

200 Successful response

application/json

dataobject · required

Nested fields

release_idstring · uuid · required

numberinteger · required

deliveryobject · required

A Masko mascot release delivery, as every Masko player reads it.

Nested fields

deliverySchemaVersionnumber · required

Values: 1

playerContractnumber · required

The rulebook version. A player refuses a version it does not know.

Values: 1

requiresarray · required

Features this graph uses. A player refuses one it does not implement.

Nested fields

string · any-state, condition-groups

targetstring · required

Values: "android", "apple", "macos", "windows", "web", "full"

modestring · required

Values: "selected", "manifest"

variantobject

Nested fields

sizeinteger

Range: 0 to unbounded

runtimeGraphobject · required

Nested fields

runtimeGraphSchemaVersionnumber · required

Values: 1

versionstring · required

Values: "2.0", "2.1"

namestring · required

canvasNamestring

initialNodestring · required

autoPlayboolean · required

clickEffectstring

Values: "ripple", "none"

targetstring

Values: "android", "apple", "macos", "windows", "web", "full"

nodesarray · required

Nested fields

idstring · required

namestring · required

transparentThumbnailUrlstring

edgesarray · required

Nested fields

idstring · required

namestring

sourcestring · required

A node id, or "*" for an Any State edge.

targetstring · required

isLoopboolean · required

durationnumber · required

Seconds.

Range: 0 to unbounded

conditionsarray

Nested fields

inputstring · required

opstring

Values: "==", "!=", ">", "<", ">=", "<="

valueobject

Nested fields

See the OpenAPI schema for deeper nested fields.

conditionGroupsarray

When present, replaces conditions: any group whose conditions all hold.

Nested fields

See the OpenAPI schema for deeper nested fields.

videosobject · required

Nested fields

webmstring

hevcstring

stackedstring

Colour above, transparency below, for Android players.

av1string

The stacked layout in AV1, for the Masko app players: in a delivery asked with formats=av1, in place of stacked or hevc.

variantsobject

Size variants by pixel size, in manifest mode.

reverseboolean

prioritynumber

speednumber

speedInputstring

A number input the clip speed follows: it plays at speed times that value, between 0.2 and 4.

movementobject

Nested fields

soundobject

Nested fields

urlstring

volumenumber

loopboolean

anchorsobject

Nested fields

hasAudioboolean

inputsarray

Nested fields

namestring · required

typestring · required

Values: "boolean", "number", "trigger"

defaultobject · required

Nested fields

Option 1

boolean

Option 2

number

systemboolean

physicsobject

Nested fields

defaultAnchorsobject

Nested fields

nodeAnchorsobject

anchorsobject

Nested fields

capabilitiesobject

Nested fields

motionProfilesobject

presentationobject

Nested fields

releaseobject

Nested fields

idstring

Names what plays: a fingerprint of the delivered graph without its links. A fresh delivery with the same id only renews the links.

listingIdstring

slugstring

mascotVersioninteger

contentHashstring · nullable

updatedAtstring

resourceKindstring

Values: "marketplace_listing", "mascot"

resourceIdstring

resourceVersionNumberinteger

runtimeBuildIdstring

runtimeContentHashstring

sourceListingIdstring · nullable

deliveryAccessobject

Nested fields

urlModestring · required

Values: "signed", "public"

signedUrlExpiresAtstring

lastFetchedAtstring · required

400 Invalid input

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Authentication required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Write key required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Resource not found in credential workspace

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Revision conflict or retained history

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

422 Required release media unavailable

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "operationId": "getCanvasReleaseDelivery",
  "tags": [
    "Canvases"
  ],
  "summary": "Get signed playback media for one immutable release",
  "description": "Call from your backend with its API key and forward only delivery to website visitors. This response contains no authoring credentials, generation context or private identity references. Creating a release does not activate it.",
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "canvasId",
      "in": "path"
    },
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "releaseId",
      "in": "path"
    },
    {
      "schema": {
        "type": "string",
        "enum": [
          "web",
          "apple",
          "android",
          "desktop"
        ],
        "default": "web",
        "description": "web returns WebM and HEVC links, apple returns HEVC links for iPhone, iPad and Mac players, android returns stacked MP4 links for Android players, desktop returns the full media set."
      },
      "required": false,
      "description": "web returns WebM and HEVC links, apple returns HEVC links for iPhone, iPad and Mac players, android returns stacked MP4 links for Android players, desktop returns the full media set.",
      "name": "target",
      "in": "query"
    },
    {
      "schema": {
        "type": "string",
        "description": "Comma-separated formats the player plays beyond its target's own. With av1 and target apple or android, every clip that has a stacked AV1 file returns it as videos.av1 in place of hevc or stacked: colour above, transparency below, 2 to 3 times lighter at the same look. The Masko player gives the value to send as MaskoPlayer.formats. Other targets ignore it."
      },
      "required": false,
      "description": "Comma-separated formats the player plays beyond its target's own. With av1 and target apple or android, every clip that has a stacked AV1 file returns it as videos.av1 in place of hevc or stacked: colour above, transparency below, 2 to 3 times lighter at the same look. The Masko player gives the value to send as MaskoPlayer.formats. Other targets ignore it.",
      "name": "formats",
      "in": "query"
    }
  ],
  "responses": {
    "200": {
      "description": "Successful response",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "release_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "number": {
                    "type": "integer"
                  },
                  "delivery": {
                    "$ref": "#/components/schemas/MascotReleaseDelivery"
                  }
                },
                "required": [
                  "release_id",
                  "number",
                  "delivery"
                ]
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Invalid input",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "401": {
      "description": "Authentication required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "403": {
      "description": "Write key required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "404": {
      "description": "Resource not found in credential workspace",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "409": {
      "description": "Revision conflict or retained history",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "422": {
      "description": "Required release media unavailable",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  },
  "x-masko-api-version": "2026-09-26"
}

GET/v1/mascots/{id}/published-libraryRead approved content through a project in the credential workspace

Requires a library license owned by the credential workspace, or a mascot authored in that workspace. A personal purchase does not grant an organization license. Organization purchases are shared with current members only within that organization. Retained purchase content is scoped to the same owner.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

project_idquery · required

string

Responses

200 Successful response

application/json

dataobject · required

Nested fields

mascot_idstring · uuid · required

contentarray · required

Nested fields

object

400 Invalid input

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Authentication required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Write key required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Resource not found in credential workspace

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Revision conflict or retained history

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

422 Required release media unavailable

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "operationId": "getPublishedMascotLibrary",
  "description": "Requires a library license owned by the credential workspace, or a mascot authored in that workspace. A personal purchase does not grant an organization license. Organization purchases are shared with current members only within that organization. Retained purchase content is scoped to the same owner.",
  "tags": [
    "Mascots"
  ],
  "summary": "Read approved content through a project in the credential workspace",
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "project_id",
      "in": "query"
    }
  ],
  "responses": {
    "200": {
      "description": "Successful response",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "mascot_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "content": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  }
                },
                "required": [
                  "mascot_id",
                  "content"
                ]
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Invalid input",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "401": {
      "description": "Authentication required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "403": {
      "description": "Write key required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "404": {
      "description": "Resource not found in credential workspace",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "409": {
      "description": "Revision conflict or retained history",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "422": {
      "description": "Required release media unavailable",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  },
  "x-masko-api-version": "2026-09-26"
}

POST/v1/auth/deviceStart device authorization for Masko CLI (remote terminals)

No bearer required. Show user_code and verification_uri_complete, then poll auth/token at interval seconds. Codes expire after 600 seconds. Explicit signed-in browser approval selects the workspace. Uses the Masko JSON envelope and device-grant semantics, not form-encoded OAuth transport.

No authentication required.

Request body (required)

application/json

client_idstring · required

Values: "masko-cli"

device_namestring · required

Length: 1 to 100 characters

Pattern: ^[^\u0000-\u001f\u007f]+$

scopestring

Values: "read", "write"

Default: "write"

Responses

200 Success. Cache-Control: no-store.

application/json

dataobject · required

Nested fields

device_codestring · required

user_codestring · required

verification_uristring · uri · required

verification_uri_completestring · uri · required

expires_innumber · required

intervalnumber · required

400 Validation or device-grant state error.

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

429 Rate limited.

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

503 Authentication service unavailable.

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "operationId": "createCLIDeviceGrant",
  "tags": [
    "Authentication"
  ],
  "summary": "Start device authorization for Masko CLI (remote terminals)",
  "description": "No bearer required. Show user_code and verification_uri_complete, then poll auth/token at interval seconds. Codes expire after 600 seconds. Explicit signed-in browser approval selects the workspace. Uses the Masko JSON envelope and device-grant semantics, not form-encoded OAuth transport.",
  "security": [],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "client_id": {
              "type": "string",
              "enum": [
                "masko-cli"
              ]
            },
            "device_name": {
              "type": "string",
              "minLength": 1,
              "maxLength": 100,
              "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
            },
            "scope": {
              "type": "string",
              "enum": [
                "read",
                "write"
              ],
              "default": "write"
            }
          },
          "required": [
            "client_id",
            "device_name"
          ],
          "additionalProperties": false
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Success. Cache-Control: no-store.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "device_code": {
                    "type": "string"
                  },
                  "user_code": {
                    "type": "string"
                  },
                  "verification_uri": {
                    "type": "string",
                    "format": "uri"
                  },
                  "verification_uri_complete": {
                    "type": "string",
                    "format": "uri"
                  },
                  "expires_in": {
                    "type": "number"
                  },
                  "interval": {
                    "type": "number"
                  }
                },
                "required": [
                  "device_code",
                  "user_code",
                  "verification_uri",
                  "verification_uri_complete",
                  "expires_in",
                  "interval"
                ]
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "400": {
      "description": "Validation or device-grant state error.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "429": {
      "description": "Rate limited.",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "503": {
      "description": "Authentication service unavailable.",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  }
}

POST/v1/auth/tokenExchange a PKCE authorization code, poll a device code, or rotate a CLI refresh token

No bearer required. For authorization_code, send code, exact redirect_uri, and the original code_verifier; S256 must match the approved challenge. Codes expire after 120 seconds and are single-use. For device grants: authorization_pending: continue polling; slow_down: add 5 seconds to every subsequent interval; access_denied, expired_token, invalid_grant: stop. Access tokens last 900 seconds. Refresh tokens rotate once per use; reuse revokes the session. Serialize refreshes and save the returned pair atomically. Sessions expire after 90 days. Never log tokens.

No authentication required.

Request body (required)

application/json

Option 1

client_idstring · required

Values: "masko-cli"

grant_typestring · required

Values: "authorization_code"

codestring · required

Pattern: ^masko_ac_[a-f0-9]{64}$

redirect_uristring · uri · required

Length: 0 to 200 characters

code_verifierstring · required

Pattern: ^[A-Za-z0-9._~-]{43,128}$

Option 2

client_idstring · required

Values: "masko-cli"

grant_typestring · required

Values: "urn:ietf:params:oauth:grant-type:device_code"

device_codestring · required

Pattern: ^masko_dc_[a-f0-9]{64}$

Option 3

client_idstring · required

Values: "masko-cli"

grant_typestring · required

Values: "refresh_token"

refresh_tokenstring · required

Pattern: ^masko_rt_[a-f0-9]{64}$

Responses

200 Success. Cache-Control: no-store.

application/json

dataobject · required

Nested fields

access_tokenstring · required

refresh_tokenstring · required

token_typestring · required

Values: "Bearer"

expires_innumber · required

session_idstring · uuid · required

session_expires_atstring · required

400 Validation or device-grant state error.

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

429 Rate limited.

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

503 Authentication service unavailable.

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "operationId": "exchangeCLIToken",
  "tags": [
    "Authentication"
  ],
  "summary": "Exchange a PKCE authorization code, poll a device code, or rotate a CLI refresh token",
  "description": "No bearer required. For authorization_code, send code, exact redirect_uri, and the original code_verifier; S256 must match the approved challenge. Codes expire after 120 seconds and are single-use. For device grants: authorization_pending: continue polling; slow_down: add 5 seconds to every subsequent interval; access_denied, expired_token, invalid_grant: stop. Access tokens last 900 seconds. Refresh tokens rotate once per use; reuse revokes the session. Serialize refreshes and save the returned pair atomically. Sessions expire after 90 days. Never log tokens.",
  "security": [],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "oneOf": [
            {
              "type": "object",
              "properties": {
                "client_id": {
                  "type": "string",
                  "enum": [
                    "masko-cli"
                  ]
                },
                "grant_type": {
                  "type": "string",
                  "enum": [
                    "authorization_code"
                  ]
                },
                "code": {
                  "type": "string",
                  "pattern": "^masko_ac_[a-f0-9]{64}$"
                },
                "redirect_uri": {
                  "type": "string",
                  "maxLength": 200,
                  "format": "uri"
                },
                "code_verifier": {
                  "type": "string",
                  "pattern": "^[A-Za-z0-9._~-]{43,128}$"
                }
              },
              "required": [
                "client_id",
                "grant_type",
                "code",
                "redirect_uri",
                "code_verifier"
              ],
              "additionalProperties": false
            },
            {
              "type": "object",
              "properties": {
                "client_id": {
                  "type": "string",
                  "enum": [
                    "masko-cli"
                  ]
                },
                "grant_type": {
                  "type": "string",
                  "enum": [
                    "urn:ietf:params:oauth:grant-type:device_code"
                  ]
                },
                "device_code": {
                  "type": "string",
                  "pattern": "^masko_dc_[a-f0-9]{64}$"
                }
              },
              "required": [
                "client_id",
                "grant_type",
                "device_code"
              ],
              "additionalProperties": false
            },
            {
              "type": "object",
              "properties": {
                "client_id": {
                  "type": "string",
                  "enum": [
                    "masko-cli"
                  ]
                },
                "grant_type": {
                  "type": "string",
                  "enum": [
                    "refresh_token"
                  ]
                },
                "refresh_token": {
                  "type": "string",
                  "pattern": "^masko_rt_[a-f0-9]{64}$"
                }
              },
              "required": [
                "client_id",
                "grant_type",
                "refresh_token"
              ],
              "additionalProperties": false
            }
          ]
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Success. Cache-Control: no-store.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "access_token": {
                    "type": "string"
                  },
                  "refresh_token": {
                    "type": "string"
                  },
                  "token_type": {
                    "type": "string",
                    "enum": [
                      "Bearer"
                    ]
                  },
                  "expires_in": {
                    "type": "number"
                  },
                  "session_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "session_expires_at": {
                    "type": "string"
                  }
                },
                "required": [
                  "access_token",
                  "refresh_token",
                  "token_type",
                  "expires_in",
                  "session_id",
                  "session_expires_at"
                ]
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "400": {
      "description": "Validation or device-grant state error.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "429": {
      "description": "Rate limited.",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "503": {
      "description": "Authentication service unavailable.",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  }
}

POST/v1/auth/revokeEnd a CLI browser session using its refresh token

Idempotent. Ends access immediately. Does not revoke API keys or other installations.

No authentication required.

Request body (required)

application/json

refresh_tokenstring · required

Pattern: ^masko_rt_[a-f0-9]{64}$

Responses

200 Success. Cache-Control: no-store.

application/json

dataobject · required

Nested fields

revokedboolean · required

400 Validation or device-grant state error.

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

429 Rate limited.

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

503 Authentication service unavailable.

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "operationId": "revokeCLISession",
  "tags": [
    "Authentication"
  ],
  "summary": "End a CLI browser session using its refresh token",
  "description": "Idempotent. Ends access immediately. Does not revoke API keys or other installations.",
  "security": [],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "refresh_token": {
              "type": "string",
              "pattern": "^masko_rt_[a-f0-9]{64}$"
            }
          },
          "required": [
            "refresh_token"
          ],
          "additionalProperties": false
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Success. Cache-Control: no-store.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "revoked": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "revoked"
                ]
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "400": {
      "description": "Validation or device-grant state error.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "429": {
      "description": "Rate limited.",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "503": {
      "description": "Authentication service unavailable.",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  }
}

GET/v1/auth/sessionIdentify the account, workspace, and credential in use

Returns the account, workspace and credential that authenticated this request. Use it to check which key an integration is using.

Bearer authentication. Access depends on credential scope and workspace membership.

Responses

200 Authenticated identity.

application/json

dataobject · required

Nested fields

user_idstring · uuid · required

emailstring

organization_idstring · uuid · nullable · required

organization_namestring · nullable · required

The team workspace name; null for a personal workspace.

permissionsstring · required

Values: "read", "write", "admin"

methodstring · required

Values: "browser", "api_key"

session_idstring · uuid · nullable · required

401 Expired, revoked, or missing credential.

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Restricted credential.

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

503 Account unavailable.

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "operationId": "getAuthSession",
  "tags": [
    "Authentication"
  ],
  "summary": "Identify the account, workspace, and credential in use",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "responses": {
    "200": {
      "description": "Authenticated identity.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "user_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "email": {
                    "type": "string"
                  },
                  "organization_id": {
                    "type": "string",
                    "nullable": true,
                    "format": "uuid"
                  },
                  "organization_name": {
                    "type": "string",
                    "nullable": true,
                    "description": "The team workspace name; null for a personal workspace."
                  },
                  "permissions": {
                    "type": "string",
                    "enum": [
                      "read",
                      "write",
                      "admin"
                    ]
                  },
                  "method": {
                    "type": "string",
                    "enum": [
                      "browser",
                      "api_key"
                    ]
                  },
                  "session_id": {
                    "type": "string",
                    "nullable": true,
                    "format": "uuid"
                  }
                },
                "required": [
                  "user_id",
                  "organization_id",
                  "organization_name",
                  "permissions",
                  "method",
                  "session_id"
                ]
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "401": {
      "description": "Expired, revoked, or missing credential.",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "403": {
      "description": "Restricted credential.",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "503": {
      "description": "Account unavailable.",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  },
  "description": "Returns the account, workspace and credential that authenticated this request. Use it to check which key an integration is using."
}

GET/v1/auth/configDiscover Masko CLI browser authorization

The registered masko-cli client opens authorization_endpoint with response_type=code, client_id=masko-cli, device_name, scope read/write, redirect_uri, state, code_challenge, and code_challenge_method=S256. Only http://127.0.0.1:PORT/oauth/callback with port 1024..65535 is accepted. Use independent random verifier and state values with at least 32 random bytes; state is echoed and must be checked by the CLI. Browser sign-in and explicit workspace approval return a one-time code, never access or refresh tokens. This is Masko JSON transport, not general OAuth server discovery.

No authentication required.

Responses

200 Configuration. Cache-Control: no-store.

application/json

dataobject · required

Nested fields

authorization_endpointstring · uri · required

code_challenge_methods_supportedarray · required

Nested fields

string · S256

grant_types_supportedarray · required

Nested fields

string · authorization_code, urn:ietf:params:oauth:grant-type:device_code, refresh_token

OpenAPI operation

{
  "operationId": "getCLIAuthConfig",
  "tags": [
    "Authentication"
  ],
  "summary": "Discover Masko CLI browser authorization",
  "security": [],
  "description": "The registered masko-cli client opens authorization_endpoint with response_type=code, client_id=masko-cli, device_name, scope read/write, redirect_uri, state, code_challenge, and code_challenge_method=S256. Only http://127.0.0.1:PORT/oauth/callback with port 1024..65535 is accepted. Use independent random verifier and state values with at least 32 random bytes; state is echoed and must be checked by the CLI. Browser sign-in and explicit workspace approval return a one-time code, never access or refresh tokens. This is Masko JSON transport, not general OAuth server discovery.",
  "responses": {
    "200": {
      "description": "Configuration. Cache-Control: no-store.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "authorization_endpoint": {
                    "type": "string",
                    "format": "uri"
                  },
                  "code_challenge_methods_supported": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "S256"
                      ]
                    }
                  },
                  "grant_types_supported": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "authorization_code",
                        "urn:ietf:params:oauth:grant-type:device_code",
                        "refresh_token"
                      ]
                    }
                  }
                },
                "required": [
                  "authorization_endpoint",
                  "code_challenge_methods_supported",
                  "grant_types_supported"
                ]
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    }
  }
}

GET/v1/collections/{id}/canvases/{canvasId}/validateValidate the stored canvas graph

Checks graph structure and assigned media references without generating media or changing the graph. Draft edges without videos report missing-video; this is expected before animation generation. GET requires read access. A structurally invalid graph still returns 200 with data.valid=false.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

canvasIdpath · required

string

Responses

200 Graph validation result.

application/json

dataobject · required

Nested fields

validboolean · required

issuesarray · required

Nested fields

severitystring · required

Values: "error", "warning"

codestring · required

messagestring · required

nodeIdstring

edgeIdstring

summaryobject · required

Nested fields

errorsnumber · required

warningsnumber · required

401 Missing or invalid credential.

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Insufficient credential permissions.

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Collection or canvas not found in this workspace.

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

500 Validation could not be completed.

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Canvases"
  ],
  "summary": "Validate the stored canvas graph",
  "description": "Checks graph structure and assigned media references without generating media or changing the graph. Draft edges without videos report missing-video; this is expected before animation generation. GET requires read access. A structurally invalid graph still returns 200 with data.valid=false.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "canvasId",
      "in": "path"
    }
  ],
  "responses": {
    "200": {
      "description": "Graph validation result.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "valid": {
                    "type": "boolean"
                  },
                  "issues": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "severity": {
                          "type": "string",
                          "enum": [
                            "error",
                            "warning"
                          ]
                        },
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "nodeId": {
                          "type": "string"
                        },
                        "edgeId": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "severity",
                        "code",
                        "message"
                      ]
                    }
                  },
                  "summary": {
                    "type": "object",
                    "properties": {
                      "errors": {
                        "type": "number"
                      },
                      "warnings": {
                        "type": "number"
                      }
                    },
                    "required": [
                      "errors",
                      "warnings"
                    ]
                  }
                },
                "required": [
                  "valid",
                  "issues",
                  "summary"
                ]
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "401": {
      "description": "Missing or invalid credential.",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "403": {
      "description": "Insufficient credential permissions.",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "404": {
      "description": "Collection or canvas not found in this workspace.",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "500": {
      "description": "Validation could not be completed.",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  },
  "deprecated": true,
  "operationId": "legacyGetCollectionCanvasValidate"
}

POST/v1/collections/{id}/canvases/{canvasId}/validateValidate the stored canvas graph

Checks graph structure and assigned media references without generating media or changing the graph. Draft edges without videos report missing-video; this is expected before animation generation. POST requires write access and accepts no body; prefer GET for read-only checks. A structurally invalid graph still returns 200 with data.valid=false.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

canvasIdpath · required

string

Idempotency-Keyheader

string

Responses

200 Graph validation result.

application/json

dataobject · required

Nested fields

validboolean · required

issuesarray · required

Nested fields

severitystring · required

Values: "error", "warning"

codestring · required

messagestring · required

nodeIdstring

edgeIdstring

summaryobject · required

Nested fields

errorsnumber · required

warningsnumber · required

401 Missing or invalid credential.

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Insufficient credential permissions.

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Collection or canvas not found in this workspace.

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

500 Validation could not be completed.

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Canvases"
  ],
  "summary": "Validate the stored canvas graph",
  "description": "Checks graph structure and assigned media references without generating media or changing the graph. Draft edges without videos report missing-video; this is expected before animation generation. POST requires write access and accepts no body; prefer GET for read-only checks. A structurally invalid graph still returns 200 with data.valid=false.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "canvasId",
      "in": "path"
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.",
      "schema": {
        "type": "string",
        "maxLength": 255
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Graph validation result.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "valid": {
                    "type": "boolean"
                  },
                  "issues": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "severity": {
                          "type": "string",
                          "enum": [
                            "error",
                            "warning"
                          ]
                        },
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "nodeId": {
                          "type": "string"
                        },
                        "edgeId": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "severity",
                        "code",
                        "message"
                      ]
                    }
                  },
                  "summary": {
                    "type": "object",
                    "properties": {
                      "errors": {
                        "type": "number"
                      },
                      "warnings": {
                        "type": "number"
                      }
                    },
                    "required": [
                      "errors",
                      "warnings"
                    ]
                  }
                },
                "required": [
                  "valid",
                  "issues",
                  "summary"
                ]
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "401": {
      "description": "Missing or invalid credential.",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "403": {
      "description": "Insufficient credential permissions.",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "404": {
      "description": "Collection or canvas not found in this workspace.",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "500": {
      "description": "Validation could not be completed.",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  },
  "deprecated": true,
  "operationId": "legacyValidateCollectionCanvas"
}

GET/v1/canvases/{canvasId}/generation-estimateEstimate canvas generation without starting jobs

Read-only cost and work preview. Accepts read or write credentials in the canvas workspace. Always runs a dry run without charging credits, creating jobs or changing the graph. Returns estimated_cost, planned_jobs, plan_id and graph_content_hash. After approval, send identical options and the returned plan identifiers to POST /v1/canvases/{canvasId}/generate-all using a write credential.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

canvasIdpath · required

string

optionsquery

URL-encoded JSON object with animation_model (standard or premium, default standard), duration (default 5; standard 2–15, premium 4–30), targets, include_stickers, skip_completed, and optional node_ids or edge_ids arrays. Execution controls such as dry_run, approved_plan_id and max_credits are rejected. This endpoint always estimates only.

string

Responses

200 Read-only generation plan

application/json

dataobject · required

Nested fields

plan_idstring

Stable identity of the exact graph, scope, prompts, and generation options. Return it as approved_plan_id when executing an approved dry-run plan.

graph_content_hashstring

Canvas revision used by this plan. Return it as expected_graph_hash when executing an approved dry-run plan.

dry_runboolean

can_dispatchboolean

targetsstring

Values: "all", "images", "stickers", "animations"

durationnumber

include_stickersboolean

skip_completedboolean

selectionobject

Nested fields

node_idsarray · nullable · required

Nested fields

string

edge_idsarray · nullable · required

Nested fields

string

jobsarray · required

Nested fields

job_idstring · uuid · required

edge_idstring

node_idstring

typestring · required

Values: "image", "edit", "sticker", "loop", "transition"

sourcestring

targetstring

item_namestring

costnumber · required

urlsobject

poll_urlstring

Follow this link to poll the job. On /v1/canvases routes it selects the mascot contract, so the job reports mascot_id.

generatedarray · required

Nested fields

object

planned_jobsarray

Nested fields

object

planned_job_countnumber

planned_nodesarray

Nested fields

object

planned_edgesarray

Nested fields

object

planned_stickersarray

Nested fields

object

skippednumber · required

skipped_itemsarray · required

Nested fields

kindstring · required

Values: "node", "edge"

idstring · required

reasonstring · required

asset_idstring · nullable

asset_statusstring

reverse_freearray · required

Nested fields

kindstring · required

Values: "edge"

idstring · required

reasonstring · required

Values: "reverse_edge_free"

reverse_of_edge_idstring · nullable · required

already_completearray · required

Nested fields

kindstring · required

Values: "node", "edge"

idstring · required

asset_idstring · required

estimated_costnumber · required

actual_costnumber · required

would_charge_creditsnumber

refunded_creditsnumber

total_jobsnumber · required

total_costnumber · required

400 Invalid options or canvas selection

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Authentication required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Credential is not allowed to use the public API

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Canvas or mascot not found in the credential workspace

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Canvas has no mascot generation context

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "operationId": "estimateCanvasGeneration",
  "tags": [
    "Canvases"
  ],
  "summary": "Estimate canvas generation without starting jobs",
  "description": "Read-only cost and work preview. Accepts read or write credentials in the canvas workspace. Always runs a dry run without charging credits, creating jobs or changing the graph. Returns estimated_cost, planned_jobs, plan_id and graph_content_hash. After approval, send identical options and the returned plan identifiers to POST /v1/canvases/{canvasId}/generate-all using a write credential.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "canvasId",
      "in": "path"
    },
    {
      "schema": {
        "type": "string",
        "default": "{}",
        "description": "URL-encoded JSON object with animation_model (standard or premium, default standard), duration (default 5; standard 2–15, premium 4–30), targets, include_stickers, skip_completed, and optional node_ids or edge_ids arrays. Execution controls such as dry_run, approved_plan_id and max_credits are rejected. This endpoint always estimates only."
      },
      "required": false,
      "description": "URL-encoded JSON object with animation_model (standard or premium, default standard), duration (default 5; standard 2–15, premium 4–30), targets, include_stickers, skip_completed, and optional node_ids or edge_ids arrays. Execution controls such as dry_run, approved_plan_id and max_credits are rejected. This endpoint always estimates only.",
      "name": "options",
      "in": "query"
    }
  ],
  "responses": {
    "200": {
      "description": "Read-only generation plan",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CanvasGenerateAllResponse"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Invalid options or canvas selection",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "401": {
      "description": "Authentication required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "403": {
      "description": "Credential is not allowed to use the public API",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "404": {
      "description": "Canvas or mascot not found in the credential workspace",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "409": {
      "description": "Canvas has no mascot generation context",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  },
  "x-masko-api-version": "2026-09-26"
}

POST/v1/credit-checkoutsCreate a hosted Stripe checkout for credits

Creates a payment link, not a charge. Requires write permission and an Idempotency-Key. Uses only the credential workspace; team purchases require the active owner. Amount is USD before checkout taxes and discounts. No payment data is accepted. Reuse identical inputs and the same key after an uncertain result. Successful responses replay for 24 hours; the checkout URL can expire sooner. Only a verified successful payment webhook grants credits.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

Idempotency-Keyheader · required

string

Request body (required)

application/json

amount_centsinteger · required

USD purchase amount in whole cents, from $10 to $10,000, before checkout taxes or discounts. Workspace comes from authentication.

Range: 1000 to 1000000

Responses

201 Hosted checkout; no payment taken

application/json

dataobject · required

Nested fields

idstring · required

Length: 0 to 255 characters

Pattern: ^cs_(?:test_|live_)?[A-Za-z0-9]+$

urlstring · uri · required

amount_centsinteger · required

currencystring · required

Values: "usd"

creditsinteger · required

organization_idstring · uuid · nullable · required

expires_atinteger · required

status_urlstring · required

400 Invalid input or missing Idempotency-Key

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Authentication required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Write permission or active team ownership required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Checkout not found for this user and workspace

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Idempotency key reused with different input or request still in progress

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

500 Checkout provider or database unavailable

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

503 Idempotency receipt unavailable; retry only with the same key

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "operationId": "createCreditCheckout",
  "tags": [
    "Credits"
  ],
  "summary": "Create a hosted Stripe checkout for credits",
  "description": "Creates a payment link, not a charge. Requires write permission and an Idempotency-Key. Uses only the credential workspace; team purchases require the active owner. Amount is USD before checkout taxes and discounts. No payment data is accepted. Reuse identical inputs and the same key after an uncertain result. Successful responses replay for 24 hours; the checkout URL can expire sooner. Only a verified successful payment webhook grants credits.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "minLength": 1,
        "maxLength": 255
      },
      "required": true,
      "name": "Idempotency-Key",
      "in": "header"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "amount_cents": {
              "type": "integer",
              "minimum": 1000,
              "maximum": 1000000,
              "description": "USD purchase amount in whole cents, from $10 to $10,000, before checkout taxes or discounts. Workspace comes from authentication."
            }
          },
          "required": [
            "amount_cents"
          ],
          "additionalProperties": false
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Hosted checkout; no payment taken",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "maxLength": 255,
                    "pattern": "^cs_(?:test_|live_)?[A-Za-z0-9]+$"
                  },
                  "url": {
                    "type": "string",
                    "format": "uri"
                  },
                  "amount_cents": {
                    "type": "integer"
                  },
                  "currency": {
                    "type": "string",
                    "enum": [
                      "usd"
                    ]
                  },
                  "credits": {
                    "type": "integer"
                  },
                  "organization_id": {
                    "type": "string",
                    "nullable": true,
                    "format": "uuid"
                  },
                  "expires_at": {
                    "type": "integer"
                  },
                  "status_url": {
                    "type": "string"
                  }
                },
                "required": [
                  "id",
                  "url",
                  "amount_cents",
                  "currency",
                  "credits",
                  "organization_id",
                  "expires_at",
                  "status_url"
                ]
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "400": {
      "description": "Invalid input or missing Idempotency-Key",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "401": {
      "description": "Authentication required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "403": {
      "description": "Write permission or active team ownership required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "404": {
      "description": "Checkout not found for this user and workspace",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "409": {
      "description": "Idempotency key reused with different input or request still in progress",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "500": {
      "description": "Checkout provider or database unavailable",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "503": {
      "description": "Idempotency receipt unavailable; retry only with the same key",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  }
}

GET/v1/credit-checkouts/{id}Read payment and credit delivery status

Read-only. Only the creating user in the same credential workspace may read the checkout; team ownership must still be active. A paid session does not guarantee credits have been delivered yet. credits_added is true only when the credit ledger contains the matching grant. Does not grant credits or return customer/payment credentials.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

Responses

200 Payment and credit delivery status

application/json

dataobject · required

Nested fields

idstring · required

Length: 0 to 255 characters

Pattern: ^cs_(?:test_|live_)?[A-Za-z0-9]+$

statusstring · nullable · required

Values: "open", "complete", "expired", null

payment_statusstring · required

Values: "paid", "unpaid", "no_payment_required"

creditsinteger · required

credits_addedboolean · required

organization_idstring · uuid · nullable · required

balancenumber · required

amount_totalinteger · nullable · required

currencystring · nullable · required

400 Invalid input or missing Idempotency-Key

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Authentication required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Write permission or active team ownership required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Checkout not found for this user and workspace

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Idempotency key reused with different input or request still in progress

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

500 Checkout provider or database unavailable

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

503 Idempotency receipt unavailable; retry only with the same key

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "operationId": "getCreditCheckout",
  "tags": [
    "Credits"
  ],
  "summary": "Read payment and credit delivery status",
  "description": "Read-only. Only the creating user in the same credential workspace may read the checkout; team ownership must still be active. A paid session does not guarantee credits have been delivered yet. credits_added is true only when the credit ledger contains the matching grant. Does not grant credits or return customer/payment credentials.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "maxLength": 255,
        "pattern": "^cs_(?:test_|live_)?[A-Za-z0-9]+$"
      },
      "required": true,
      "name": "id",
      "in": "path"
    }
  ],
  "responses": {
    "200": {
      "description": "Payment and credit delivery status",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "maxLength": 255,
                    "pattern": "^cs_(?:test_|live_)?[A-Za-z0-9]+$"
                  },
                  "status": {
                    "type": "string",
                    "nullable": true,
                    "enum": [
                      "open",
                      "complete",
                      "expired",
                      null
                    ]
                  },
                  "payment_status": {
                    "type": "string",
                    "enum": [
                      "paid",
                      "unpaid",
                      "no_payment_required"
                    ]
                  },
                  "credits": {
                    "type": "integer"
                  },
                  "credits_added": {
                    "type": "boolean"
                  },
                  "organization_id": {
                    "type": "string",
                    "nullable": true,
                    "format": "uuid"
                  },
                  "balance": {
                    "type": "number"
                  },
                  "amount_total": {
                    "type": "integer",
                    "nullable": true
                  },
                  "currency": {
                    "type": "string",
                    "nullable": true
                  }
                },
                "required": [
                  "id",
                  "status",
                  "payment_status",
                  "credits",
                  "credits_added",
                  "organization_id",
                  "balance",
                  "amount_total",
                  "currency"
                ]
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "400": {
      "description": "Invalid input or missing Idempotency-Key",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "401": {
      "description": "Authentication required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "403": {
      "description": "Write permission or active team ownership required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "404": {
      "description": "Checkout not found for this user and workspace",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "409": {
      "description": "Idempotency key reused with different input or request still in progress",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "500": {
      "description": "Checkout provider or database unavailable",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "503": {
      "description": "Idempotency receipt unavailable; retry only with the same key",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  }
}

POST/v1/credit-paymentsTest a direct Shared Payment Token credit purchase (local sandbox only)

Unavailable in production. Requires explicit sandbox configuration and local Supabase. Attempts a test payment using a payer-issued SPT and the same USD base credit pricing as Checkout; no taxes or discounts are calculated. Requires write permission and Idempotency-Key; team purchases require active ownership. Workspace comes from authentication. The caller must obtain user approval for this exact purchase before submitting the token over HTTPS (HTTP only on localhost). Never put payment tokens in prompts or URLs. Only the dedicated signature-verified sandbox webhook grants credits. This is not MPP, a Muse-specific payment contract, or a Managed Payments integration. Never retry an uncertain outcome with a new key or token.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

Idempotency-Keyheader · required

string

Request body (required)

application/json

amount_centsinteger · required

USD purchase amount in whole cents, from $10 to $10,000, before checkout taxes or discounts. Workspace comes from authentication.

Range: 1000 to 1000000

shared_payment_tokenstring · required

Sandbox Shared Payment Token issued by the payer wallet for this approved purchase. Never put it in a prompt, URL, log or saved card field.

Length: 0 to 255 characters

Pattern: ^spt_[A-Za-z0-9_]+$

Responses

201 Sandbox payment status; credits_added is backed by the ledger

application/json

dataobject · required

Nested fields

idstring · required

statusstring · required

Values: "requires_payment_method", "requires_confirmation", "requires_action", "processing", "requires_capture", "canceled", "succeeded"

amount_centsinteger · required

currencystring · required

Values: "usd"

creditsinteger · required

credits_addedboolean · required

organization_idstring · uuid · nullable · required

livemodeboolean · required

Values: false

status_urlstring · required

202 Sandbox payment status; credits_added is backed by the ledger

application/json

dataobject · required

Nested fields

idstring · required

statusstring · required

Values: "requires_payment_method", "requires_confirmation", "requires_action", "processing", "requires_capture", "canceled", "succeeded"

amount_centsinteger · required

currencystring · required

Values: "usd"

creditsinteger · required

credits_addedboolean · required

organization_idstring · uuid · nullable · required

livemodeboolean · required

Values: false

status_urlstring · required

400 Invalid input or missing Idempotency-Key

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Authentication required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Write permission or active team ownership required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Payment or token not found in this account/workspace

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Operation conflict or unconfirmed execution

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

422 Token rejected or payment needs unsupported customer action

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

500 Invalid payment record

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

503 Sandbox disabled, provider unavailable, or payment outcome unknown

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "operationId": "createCreditPayment",
  "tags": [
    "Credits"
  ],
  "summary": "Test a direct Shared Payment Token credit purchase (local sandbox only)",
  "description": "Unavailable in production. Requires explicit sandbox configuration and local Supabase. Attempts a test payment using a payer-issued SPT and the same USD base credit pricing as Checkout; no taxes or discounts are calculated. Requires write permission and Idempotency-Key; team purchases require active ownership. Workspace comes from authentication. The caller must obtain user approval for this exact purchase before submitting the token over HTTPS (HTTP only on localhost). Never put payment tokens in prompts or URLs. Only the dedicated signature-verified sandbox webhook grants credits. This is not MPP, a Muse-specific payment contract, or a Managed Payments integration. Never retry an uncertain outcome with a new key or token.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "minLength": 1,
        "maxLength": 255
      },
      "required": true,
      "name": "Idempotency-Key",
      "in": "header"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "amount_cents": {
              "type": "integer",
              "minimum": 1000,
              "maximum": 1000000,
              "description": "USD purchase amount in whole cents, from $10 to $10,000, before checkout taxes or discounts. Workspace comes from authentication."
            },
            "shared_payment_token": {
              "type": "string",
              "maxLength": 255,
              "pattern": "^spt_[A-Za-z0-9_]+$",
              "description": "Sandbox Shared Payment Token issued by the payer wallet for this approved purchase. Never put it in a prompt, URL, log or saved card field."
            }
          },
          "required": [
            "amount_cents",
            "shared_payment_token"
          ],
          "additionalProperties": false
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Sandbox payment status; credits_added is backed by the ledger",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "requires_payment_method",
                      "requires_confirmation",
                      "requires_action",
                      "processing",
                      "requires_capture",
                      "canceled",
                      "succeeded"
                    ]
                  },
                  "amount_cents": {
                    "type": "integer"
                  },
                  "currency": {
                    "type": "string",
                    "enum": [
                      "usd"
                    ]
                  },
                  "credits": {
                    "type": "integer"
                  },
                  "credits_added": {
                    "type": "boolean"
                  },
                  "organization_id": {
                    "type": "string",
                    "nullable": true,
                    "format": "uuid"
                  },
                  "livemode": {
                    "type": "boolean",
                    "enum": [
                      false
                    ]
                  },
                  "status_url": {
                    "type": "string"
                  }
                },
                "required": [
                  "id",
                  "status",
                  "amount_cents",
                  "currency",
                  "credits",
                  "credits_added",
                  "organization_id",
                  "livemode",
                  "status_url"
                ]
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "202": {
      "description": "Sandbox payment status; credits_added is backed by the ledger",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "requires_payment_method",
                      "requires_confirmation",
                      "requires_action",
                      "processing",
                      "requires_capture",
                      "canceled",
                      "succeeded"
                    ]
                  },
                  "amount_cents": {
                    "type": "integer"
                  },
                  "currency": {
                    "type": "string",
                    "enum": [
                      "usd"
                    ]
                  },
                  "credits": {
                    "type": "integer"
                  },
                  "credits_added": {
                    "type": "boolean"
                  },
                  "organization_id": {
                    "type": "string",
                    "nullable": true,
                    "format": "uuid"
                  },
                  "livemode": {
                    "type": "boolean",
                    "enum": [
                      false
                    ]
                  },
                  "status_url": {
                    "type": "string"
                  }
                },
                "required": [
                  "id",
                  "status",
                  "amount_cents",
                  "currency",
                  "credits",
                  "credits_added",
                  "organization_id",
                  "livemode",
                  "status_url"
                ]
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "400": {
      "description": "Invalid input or missing Idempotency-Key",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "401": {
      "description": "Authentication required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "403": {
      "description": "Write permission or active team ownership required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "404": {
      "description": "Payment or token not found in this account/workspace",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "409": {
      "description": "Operation conflict or unconfirmed execution",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "422": {
      "description": "Token rejected or payment needs unsupported customer action",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "500": {
      "description": "Invalid payment record",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "503": {
      "description": "Sandbox disabled, provider unavailable, or payment outcome unknown",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  }
}

GET/v1/credit-payments/{id}Read a sandbox token payment and credit delivery status

Unavailable in production. Read-only; never grants credits. Requires the creating user and exact workspace, with active ownership for teams. Returns no token, client secret, payment method or customer information. A succeeded payment can precede webhook credit delivery. This endpoint uses the dedicated sandbox Stripe account, never the existing live Checkout client.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

Responses

200 Sandbox payment status; credits_added is backed by the ledger

application/json

dataobject · required

Nested fields

idstring · required

statusstring · required

Values: "requires_payment_method", "requires_confirmation", "requires_action", "processing", "requires_capture", "canceled", "succeeded"

amount_centsinteger · required

currencystring · required

Values: "usd"

creditsinteger · required

credits_addedboolean · required

organization_idstring · uuid · nullable · required

livemodeboolean · required

Values: false

status_urlstring · required

400 Invalid input or missing Idempotency-Key

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Authentication required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Write permission or active team ownership required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Payment or token not found in this account/workspace

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Operation conflict or unconfirmed execution

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

422 Token rejected or payment needs unsupported customer action

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

500 Invalid payment record

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

503 Sandbox disabled, provider unavailable, or payment outcome unknown

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "operationId": "getCreditPayment",
  "tags": [
    "Credits"
  ],
  "summary": "Read a sandbox token payment and credit delivery status",
  "description": "Unavailable in production. Read-only; never grants credits. Requires the creating user and exact workspace, with active ownership for teams. Returns no token, client secret, payment method or customer information. A succeeded payment can precede webhook credit delivery. This endpoint uses the dedicated sandbox Stripe account, never the existing live Checkout client.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "maxLength": 255,
        "pattern": "^pi_[A-Za-z0-9]+$"
      },
      "required": true,
      "name": "id",
      "in": "path"
    }
  ],
  "responses": {
    "200": {
      "description": "Sandbox payment status; credits_added is backed by the ledger",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "requires_payment_method",
                      "requires_confirmation",
                      "requires_action",
                      "processing",
                      "requires_capture",
                      "canceled",
                      "succeeded"
                    ]
                  },
                  "amount_cents": {
                    "type": "integer"
                  },
                  "currency": {
                    "type": "string",
                    "enum": [
                      "usd"
                    ]
                  },
                  "credits": {
                    "type": "integer"
                  },
                  "credits_added": {
                    "type": "boolean"
                  },
                  "organization_id": {
                    "type": "string",
                    "nullable": true,
                    "format": "uuid"
                  },
                  "livemode": {
                    "type": "boolean",
                    "enum": [
                      false
                    ]
                  },
                  "status_url": {
                    "type": "string"
                  }
                },
                "required": [
                  "id",
                  "status",
                  "amount_cents",
                  "currency",
                  "credits",
                  "credits_added",
                  "organization_id",
                  "livemode",
                  "status_url"
                ]
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "400": {
      "description": "Invalid input or missing Idempotency-Key",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "401": {
      "description": "Authentication required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "403": {
      "description": "Write permission or active team ownership required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "404": {
      "description": "Payment or token not found in this account/workspace",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "409": {
      "description": "Operation conflict or unconfirmed execution",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "422": {
      "description": "Token rejected or payment needs unsupported customer action",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "500": {
      "description": "Invalid payment record",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "503": {
      "description": "Sandbox disabled, provider unavailable, or payment outcome unknown",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  }
}

POST/v1/feedbackSend feedback to the Masko team

A direct channel to the Masko team about anything Masko: a product feature, the MCP server, the REST API or the docs. Agents should use it whenever they or their user hit a rough edge, an unclear field or error, a wrong result or a missing capability, or when something worked really well; praise and feature requests are welcome. Only summary is required. Write friction_points, suggested_improvement and details as short bullets quoting exact endpoints, fields or error text, and never include personal data or secrets. Read-only credentials may send feedback. Limited to 5 a minute and 30 a day per account. The team reads every message and may reply to the account email. Sending feedback is a side report: carry on with the task afterwards.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

Idempotency-Keyheader

string

Request body (required)

application/json

summarystring · required

One sentence: what happened, what is missing or what worked well.

Length: 1 to 500 characters

feedback_typestring

product: a Masko feature such as mascots, animations, canvases, exports or billing; set product_area. mcp: the MCP server, its tools, inputs, responses or errors. api: the REST API. docs: the documentation. other: anything else.

Values: "product", "mcp", "api", "docs", "other"

Default: "other"

product_areastring

For product feedback, the area, for example "canvas".

Length: 1 to 100 characters

categorystring

For mcp and api feedback, what kind of problem it is.

Values: "unclear_description", "confusing_input", "hard_to_read_response", "wrong_result", "unhelpful_error", "missing_capability", "other"

sentimentstring

Praise and feature requests are welcome, not only problems.

Values: "positive", "neutral", "negative", "mixed"

friction_pointsstring

Short bullet points quoting the exact tool, field, endpoint or error text.

Length: 1 to 2000 characters

suggested_improvementstring

What Masko should change, when you can name it.

Length: 1 to 2000 characters

detailsstring

Anything else, as short bullets.

Length: 1 to 8000 characters

task_completedboolean

false when you could not finish what the user asked.

resource_idstring · uuid

The job, canvas, mascot or asset this is about.

agentstring

The app and model sending this, for example "Claude Code, claude-opus-5-5".

Length: 1 to 200 characters

Responses

201 Feedback received

application/json

dataobject · required

Nested fields

idstring · uuid · required

objectstring · required

Values: "feedback"

created_atstring · required

400 Missing summary or invalid field

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Authentication required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

429 More than 5 a minute or 30 a day

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

500 Feedback could not be saved

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "operationId": "sendFeedback",
  "tags": [
    "Feedback"
  ],
  "summary": "Send feedback to the Masko team",
  "description": "A direct channel to the Masko team about anything Masko: a product feature, the MCP server, the REST API or the docs. Agents should use it whenever they or their user hit a rough edge, an unclear field or error, a wrong result or a missing capability, or when something worked really well; praise and feature requests are welcome. Only summary is required. Write friction_points, suggested_improvement and details as short bullets quoting exact endpoints, fields or error text, and never include personal data or secrets. Read-only credentials may send feedback. Limited to 5 a minute and 30 a day per account. The team reads every message and may reply to the account email. Sending feedback is a side report: carry on with the task afterwards.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "summary": {
              "type": "string",
              "minLength": 1,
              "maxLength": 500,
              "description": "One sentence: what happened, what is missing or what worked well."
            },
            "feedback_type": {
              "type": "string",
              "enum": [
                "product",
                "mcp",
                "api",
                "docs",
                "other"
              ],
              "default": "other",
              "description": "product: a Masko feature such as mascots, animations, canvases, exports or billing; set product_area. mcp: the MCP server, its tools, inputs, responses or errors. api: the REST API. docs: the documentation. other: anything else."
            },
            "product_area": {
              "type": "string",
              "minLength": 1,
              "maxLength": 100,
              "description": "For product feedback, the area, for example \"canvas\"."
            },
            "category": {
              "type": "string",
              "enum": [
                "unclear_description",
                "confusing_input",
                "hard_to_read_response",
                "wrong_result",
                "unhelpful_error",
                "missing_capability",
                "other"
              ],
              "description": "For mcp and api feedback, what kind of problem it is."
            },
            "sentiment": {
              "type": "string",
              "enum": [
                "positive",
                "neutral",
                "negative",
                "mixed"
              ],
              "description": "Praise and feature requests are welcome, not only problems."
            },
            "friction_points": {
              "type": "string",
              "minLength": 1,
              "maxLength": 2000,
              "description": "Short bullet points quoting the exact tool, field, endpoint or error text."
            },
            "suggested_improvement": {
              "type": "string",
              "minLength": 1,
              "maxLength": 2000,
              "description": "What Masko should change, when you can name it."
            },
            "details": {
              "type": "string",
              "minLength": 1,
              "maxLength": 8000,
              "description": "Anything else, as short bullets."
            },
            "task_completed": {
              "type": "boolean",
              "description": "false when you could not finish what the user asked."
            },
            "resource_id": {
              "type": "string",
              "format": "uuid",
              "description": "The job, canvas, mascot or asset this is about."
            },
            "agent": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200,
              "description": "The app and model sending this, for example \"Claude Code, claude-opus-5-5\"."
            }
          },
          "required": [
            "summary"
          ],
          "additionalProperties": false
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Feedback received",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "object": {
                    "type": "string",
                    "enum": [
                      "feedback"
                    ]
                  },
                  "created_at": {
                    "type": "string"
                  }
                },
                "required": [
                  "id",
                  "object",
                  "created_at"
                ]
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "400": {
      "description": "Missing summary or invalid field",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "401": {
      "description": "Authentication required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "429": {
      "description": "More than 5 a minute or 30 a day",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "500": {
      "description": "Feedback could not be saved",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  },
  "parameters": [
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.",
      "schema": {
        "type": "string",
        "maxLength": 255
      }
    }
  ]
}

GET/v1/collections/{id}/variantsList named mascot variants

Lists the collection’s named generation contexts. Variant authoring follows collection project permissions, including authorized teammates; API keys must match the collection workspace. Create and approve variants through the API or web app, then pass the id as variant_id to /generate. Selecting a generation variant does not change active playback. A null approved_at means the variant is still a draft.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

limitquery

Page size. 1 to 100. Defaults to 50.

number

offsetquery

Number of records to skip. Defaults to 0.

number

cursorquery

Opaque next_cursor from the previous page. Use instead of offset.

string

Responses

200 Variants in creation order

application/json

dataarray · required

Nested fields

idstring · uuid · required

namestring · required

descriptionstring · required

approved_atstring · nullable · required

canvas_idstring · uuid · nullable · required

reference_asset_idstring · uuid · nullable · required

created_atstring · required

metaobject · required

Nested fields

paginationobject · required

Nested fields

totalnumber · required

limitnumber · required

offsetnumber · required

has_moreboolean · required

401 Authentication required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Mascot not found in this workspace

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "operationId": "legacyListCollectionVariants",
  "tags": [
    "Collections"
  ],
  "summary": "List named mascot variants",
  "description": "Lists the collection’s named generation contexts. Variant authoring follows collection project permissions, including authorized teammates; API keys must match the collection workspace. Create and approve variants through the API or web app, then pass the id as variant_id to /generate. Selecting a generation variant does not change active playback. A null approved_at means the variant is still a draft.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "schema": {
        "type": "number",
        "minimum": 1,
        "maximum": 100,
        "default": 50,
        "description": "Page size. 1 to 100. Defaults to 50."
      },
      "required": false,
      "description": "Page size. 1 to 100. Defaults to 50.",
      "name": "limit",
      "in": "query"
    },
    {
      "schema": {
        "type": "number",
        "nullable": true,
        "minimum": 0,
        "default": 0,
        "description": "Number of records to skip. Defaults to 0."
      },
      "required": false,
      "description": "Number of records to skip. Defaults to 0.",
      "name": "offset",
      "in": "query"
    },
    {
      "schema": {
        "type": "string",
        "description": "Opaque next_cursor from the previous page. Use instead of offset."
      },
      "required": false,
      "description": "Opaque next_cursor from the previous page. Use instead of offset.",
      "name": "cursor",
      "in": "query"
    }
  ],
  "responses": {
    "200": {
      "description": "Variants in creation order",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/MascotVariant"
                }
              },
              "meta": {
                "type": "object",
                "properties": {
                  "pagination": {
                    "type": "object",
                    "properties": {
                      "total": {
                        "type": "number"
                      },
                      "limit": {
                        "type": "number"
                      },
                      "offset": {
                        "type": "number"
                      },
                      "has_more": {
                        "type": "boolean"
                      }
                    },
                    "required": [
                      "total",
                      "limit",
                      "offset",
                      "has_more"
                    ]
                  }
                },
                "required": [
                  "pagination"
                ]
              }
            },
            "required": [
              "data",
              "meta"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "401": {
      "description": "Authentication required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "404": {
      "description": "Mascot not found in this workspace",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  },
  "deprecated": true
}

POST/v1/collections/{id}/variantsCreate a named mascot variant

Creates a draft from Original or source_variant_id. The source context and references are frozen. Supply reference_asset_id to use an existing collection image or your unassigned /v1/upload image and immediately approve the context, with no generation charge. Otherwise generate and approve a reference next. Reuse id for retries with the same inputs. This does not activate playback.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

Idempotency-Keyheader

string

Request body

application/json

idstring · uuid · required

Client-generated UUID. Reuse it to safely retry creation.

namestring · required

Length: 1 to 80 characters

descriptionstring · required

The desired change and generation guidance.

Length: 1 to 3000 characters

source_variant_idstring · uuid

Approved variant to start from. Omit for Original. Its references and context are frozen on creation.

reference_asset_idstring · uuid

Completed image in this collection, or your unassigned POST /v1/upload image. Creates an approved context immediately; no generation charge. Omit to create a draft for reference generation.

Responses

201 Created variant

application/json

dataobject · required

Nested fields

idstring · uuid · required

namestring · required

descriptionstring · required

approved_atstring · nullable · required

canvas_idstring · uuid · nullable · required

reference_asset_idstring · uuid · nullable · required

created_atstring · required

400 Invalid request or reference

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Authentication required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Variant creator required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Collection, variant or reference not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Draft source, changed operation inputs, or candidate not ready

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "operationId": "legacyCreateCollectionVariant",
  "tags": [
    "Collections"
  ],
  "summary": "Create a named mascot variant",
  "description": "Creates a draft from Original or source_variant_id. The source context and references are frozen. Supply reference_asset_id to use an existing collection image or your unassigned /v1/upload image and immediately approve the context, with no generation charge. Otherwise generate and approve a reference next. Reuse id for retries with the same inputs. This does not activate playback.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.",
      "schema": {
        "type": "string",
        "maxLength": 255
      }
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/CreateMascotVariantBody"
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Created variant",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/MascotVariant"
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "400": {
      "description": "Invalid request or reference",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "401": {
      "description": "Authentication required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "403": {
      "description": "Variant creator required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "404": {
      "description": "Collection, variant or reference not found",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "409": {
      "description": "Draft source, changed operation inputs, or candidate not ready",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  },
  "deprecated": true
}

GET/v1/collections/{id}/variants/{variantId}Read a variant and its reference candidates

Returns one variant with its reference candidates and approval state.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

variantIdpath · required

string

Responses

200 Variant and candidate previews

application/json

dataobject · required

Nested fields

variantobject · required

Nested fields

idstring · uuid · required

namestring · required

descriptionstring · required

approved_atstring · nullable · required

canvas_idstring · uuid · nullable · required

reference_asset_idstring · uuid · nullable · required

created_atstring · required

candidatesarray · required

Nested fields

idstring · uuid · required

asset_idstring · uuid · nullable · required

job_idstring · uuid · nullable · required

created_atstring · required

statusstring · required

errorstring · nullable

urlstring · nullable · required

400 Invalid request or reference

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Authentication required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Variant creator required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Collection, variant or reference not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Draft source, changed operation inputs, or candidate not ready

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "operationId": "legacyGetCollectionVariant",
  "tags": [
    "Collections"
  ],
  "summary": "Read a variant and its reference candidates",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "variantId",
      "in": "path"
    }
  ],
  "responses": {
    "200": {
      "description": "Variant and candidate previews",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/MascotVariantDetail"
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "400": {
      "description": "Invalid request or reference",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "401": {
      "description": "Authentication required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "403": {
      "description": "Variant creator required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "404": {
      "description": "Collection, variant or reference not found",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "409": {
      "description": "Draft source, changed operation inputs, or candidate not ready",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  },
  "deprecated": true,
  "description": "Returns one variant with its reference candidates and approval state."
}

POST/v1/collections/{id}/variants/{variantId}/referenceGenerate a draft variant reference

Costs 1 credit. Uses the frozen source references and the requested variant description. Reuse operation_id to retry the same job. Poll the job, inspect candidates with GET variant, then approve the selected candidate.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

variantIdpath · required

string

Idempotency-Keyheader

string

Request body

application/json

operation_idstring · uuid · required

Client-generated UUID. Reuse to retry the same candidate job without another charge.

Responses

202 Reference generation queued

application/json

dataobject · required

Nested fields

job_idstring · uuid · required

candidate_idstring · uuid · required

variant_idstring · uuid · required

estimated_costnumber · required

poll_urlstring · required

400 Invalid request or reference

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Authentication required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

402 Not enough credits

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Variant creator required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Collection, variant or reference not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Draft source, changed operation inputs, or candidate not ready

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "operationId": "legacyCreateCollectionVariantReference",
  "tags": [
    "Collections"
  ],
  "summary": "Generate a draft variant reference",
  "description": "Costs 1 credit. Uses the frozen source references and the requested variant description. Reuse operation_id to retry the same job. Poll the job, inspect candidates with GET variant, then approve the selected candidate.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "variantId",
      "in": "path"
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.",
      "schema": {
        "type": "string",
        "maxLength": 255
      }
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/GenerateVariantReferenceBody"
        }
      }
    }
  },
  "responses": {
    "202": {
      "description": "Reference generation queued",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "job_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "candidate_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "variant_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "estimated_cost": {
                    "type": "number"
                  },
                  "poll_url": {
                    "type": "string"
                  }
                },
                "required": [
                  "job_id",
                  "candidate_id",
                  "variant_id",
                  "estimated_cost",
                  "poll_url"
                ]
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "400": {
      "description": "Invalid request or reference",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "401": {
      "description": "Authentication required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "402": {
      "description": "Not enough credits",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "403": {
      "description": "Variant creator required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "404": {
      "description": "Collection, variant or reference not found",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "409": {
      "description": "Draft source, changed operation inputs, or candidate not ready",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  },
  "deprecated": true
}

POST/v1/collections/{id}/variants/{variantId}/approveApprove a generated variant reference

Select a completed candidate belonging to this variant. Creates its canvas and makes variant_id usable for generation. Does not generate poses or change active playback. Repeating approval of the same candidate is safe.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

variantIdpath · required

string

Idempotency-Keyheader

string

Request body

application/json

candidate_idstring · uuid · required

Completed candidate from this variant to use as its reference.

Responses

200 Approved variant

application/json

dataobject · required

Nested fields

idstring · uuid · required

namestring · required

descriptionstring · required

approved_atstring · nullable · required

canvas_idstring · uuid · nullable · required

reference_asset_idstring · uuid · nullable · required

created_atstring · required

400 Invalid request or reference

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Authentication required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Variant creator required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Collection, variant or reference not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Draft source, changed operation inputs, or candidate not ready

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "operationId": "legacyApproveCollectionVariant",
  "tags": [
    "Collections"
  ],
  "summary": "Approve a generated variant reference",
  "description": "Select a completed candidate belonging to this variant. Creates its canvas and makes variant_id usable for generation. Does not generate poses or change active playback. Repeating approval of the same candidate is safe.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "variantId",
      "in": "path"
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.",
      "schema": {
        "type": "string",
        "maxLength": 255
      }
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApproveMascotVariantBody"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Approved variant",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/MascotVariant"
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "400": {
      "description": "Invalid request or reference",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "401": {
      "description": "Authentication required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "403": {
      "description": "Variant creator required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "404": {
      "description": "Collection, variant or reference not found",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "409": {
      "description": "Draft source, changed operation inputs, or candidate not ready",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  },
  "deprecated": true
}

POST/v1/collections/{id}/interactiveGenerate a follow-cursor interaction

Creates nine 1024×1024 transparent gaze directions from one completed image. Requires a completed transparent source or transparent derivative in the same collection. Preserves the source variant automatically; no variant_id override. Optional name (maximum 60 characters after trimming) labels only the interaction; omitted or blank names use the source image name without renaming the image. Costs 9 credits. Returns an asynchronous job receipt. Send once and poll the returned job URL; repeating POST creates and charges a new set. Hosted collections automatically publish a JSON manifest and nine lossless WebPs. Retrieve them with GET /v1/collections/{id}/cdn-export after completion. This interaction is independent of Canvas state machines.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

Idempotency-Keyheader

string

Request body (required)

application/json

source_asset_idstring · uuid · required

kindstring · required

Values: "cursor-follower"

namestring

Interaction label. Omitted or blank names use the source image name without renaming the image.

Length: 0 to 60 characters

Responses

202 Nine-direction generation queued

application/json

dataobject · required

Nested fields

job_idstring · uuid · required

asset_idstring · uuid · required

asset_idsobject · required

Nested fields

interactivestring · uuid · required

statusstring · required

Values: "pending"

estimated_costnumber · required

variant_idstring · uuid · nullable · required

poll_urlstring · required

400 Invalid request

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

402 Insufficient credits

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Write access required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Collection or completed source not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

422 Transparent image required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

429 Rate limited

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

500 Could not queue generation

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "operationId": "legacyCreateCollectionInteractive",
  "tags": [
    "Generate"
  ],
  "summary": "Generate a follow-cursor interaction",
  "description": "Creates nine 1024×1024 transparent gaze directions from one completed image. Requires a completed transparent source or transparent derivative in the same collection. Preserves the source variant automatically; no variant_id override. Optional name (maximum 60 characters after trimming) labels only the interaction; omitted or blank names use the source image name without renaming the image. Costs 9 credits. Returns an asynchronous job receipt. Send once and poll the returned job URL; repeating POST creates and charges a new set. Hosted collections automatically publish a JSON manifest and nine lossless WebPs. Retrieve them with GET /v1/collections/{id}/cdn-export after completion. This interaction is independent of Canvas state machines.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.",
      "schema": {
        "type": "string",
        "maxLength": 255
      }
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/CreateInteractionBody"
        }
      }
    }
  },
  "responses": {
    "202": {
      "description": "Nine-direction generation queued",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/InteractionGenerationResponse"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "400": {
      "description": "Invalid request",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "402": {
      "description": "Insufficient credits",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "403": {
      "description": "Write access required",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "404": {
      "description": "Collection or completed source not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "422": {
      "description": "Transparent image required",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "429": {
      "description": "Rate limited",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "500": {
      "description": "Could not queue generation",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    }
  },
  "deprecated": true
}

GET/v1/logo-stylesList logo style presets

Nine logo treatments shared with the dashboard, including preview URLs and full instructions. Use id as logo_style_id when generating a logo. No credit cost.

Bearer authentication. Access depends on credential scope and workspace membership.

Responses

200 Logo styles

application/json

dataarray · required

Nested fields

idstring · required

Values: "graphic-app-icon", "cut-paper", "soft-depth", "geometric", "abstract-symbol", "monoline-symbol", "negative-space", "retro-emblem", "hand-drawn"

namestring · required

descriptionstring · required

instructionstring · required

preview_urlstring · required

400 Invalid request

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

402 Insufficient credits

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Write access required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Source or collection not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Request ID conflict or variant not approved

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

429 Rate limited

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

500 Internal error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

503 Generation unavailable

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "operationId": "listLogoStyles",
  "tags": [
    "Styles"
  ],
  "summary": "List logo style presets",
  "description": "Nine logo treatments shared with the dashboard, including preview URLs and full instructions. Use id as logo_style_id when generating a logo. No credit cost.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "responses": {
    "200": {
      "description": "Logo styles",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "enum": [
                        "graphic-app-icon",
                        "cut-paper",
                        "soft-depth",
                        "geometric",
                        "abstract-symbol",
                        "monoline-symbol",
                        "negative-space",
                        "retro-emblem",
                        "hand-drawn"
                      ]
                    },
                    "name": {
                      "type": "string"
                    },
                    "description": {
                      "type": "string"
                    },
                    "instruction": {
                      "type": "string"
                    },
                    "preview_url": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "id",
                    "name",
                    "description",
                    "instruction",
                    "preview_url"
                  ]
                }
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "400": {
      "description": "Invalid request",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "402": {
      "description": "Insufficient credits",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "403": {
      "description": "Write access required",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "404": {
      "description": "Source or collection not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "409": {
      "description": "Request ID conflict or variant not approved",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "429": {
      "description": "Rate limited",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "500": {
      "description": "Internal error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "503": {
      "description": "Generation unavailable",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    }
  }
}

GET/v1/collections/{id}/logos/suggestionsSuggest logo directions and styles

Five directions, including face portrait and full body, plus three suggested styles. Each direction can include a style. A style can be custom; preset_id is present only when it exactly matches a built-in preset. Returns defaults if generation is unavailable, unless refresh=true, which returns 503. No image credits; does not change the collection.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

variant_idquery

string

refreshquery

string · true, false

Responses

200 Logo ideas

application/json

dataobject · required

Nested fields

prompt_versionnumber · required

cachedboolean · required

descriptionsarray · required

Nested fields

namestring · required

descriptionstring · required

styleobject · nullable

Nested fields

namestring · required

instructionstring · required

preset_idstring

Values: "graphic-app-icon", "cut-paper", "soft-depth", "geometric", "abstract-symbol", "monoline-symbol", "negative-space", "retro-emblem", "hand-drawn"

stylesarray · required

Nested fields

namestring · required

instructionstring · required

preset_idstring

Values: "graphic-app-icon", "cut-paper", "soft-depth", "geometric", "abstract-symbol", "monoline-symbol", "negative-space", "retro-emblem", "hand-drawn"

400 Invalid request

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

402 Insufficient credits

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Write access required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Source or collection not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Request ID conflict or variant not approved

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

429 Rate limited

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

500 Internal error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

503 Generation unavailable

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "operationId": "legacyListCollectionLogoSuggestions",
  "tags": [
    "Suggestions"
  ],
  "summary": "Suggest logo directions and styles",
  "description": "Five directions, including face portrait and full body, plus three suggested styles. Each direction can include a style. A style can be custom; preset_id is present only when it exactly matches a built-in preset. Returns defaults if generation is unavailable, unless refresh=true, which returns 503. No image credits; does not change the collection.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": false,
      "name": "variant_id",
      "in": "query"
    },
    {
      "schema": {
        "type": "string",
        "enum": [
          "true",
          "false"
        ]
      },
      "required": false,
      "name": "refresh",
      "in": "query"
    }
  ],
  "responses": {
    "200": {
      "description": "Logo ideas",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "prompt_version": {
                    "type": "number"
                  },
                  "cached": {
                    "type": "boolean"
                  },
                  "descriptions": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string"
                        },
                        "description": {
                          "type": "string"
                        },
                        "style": {
                          "type": "object",
                          "nullable": true,
                          "properties": {
                            "name": {
                              "type": "string"
                            },
                            "instruction": {
                              "type": "string"
                            },
                            "preset_id": {
                              "type": "string",
                              "enum": [
                                "graphic-app-icon",
                                "cut-paper",
                                "soft-depth",
                                "geometric",
                                "abstract-symbol",
                                "monoline-symbol",
                                "negative-space",
                                "retro-emblem",
                                "hand-drawn"
                              ]
                            }
                          },
                          "required": [
                            "name",
                            "instruction"
                          ]
                        }
                      },
                      "required": [
                        "name",
                        "description"
                      ]
                    }
                  },
                  "styles": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string"
                        },
                        "instruction": {
                          "type": "string"
                        },
                        "preset_id": {
                          "type": "string",
                          "enum": [
                            "graphic-app-icon",
                            "cut-paper",
                            "soft-depth",
                            "geometric",
                            "abstract-symbol",
                            "monoline-symbol",
                            "negative-space",
                            "retro-emblem",
                            "hand-drawn"
                          ]
                        }
                      },
                      "required": [
                        "name",
                        "instruction"
                      ]
                    }
                  }
                },
                "required": [
                  "prompt_version",
                  "cached",
                  "descriptions",
                  "styles"
                ]
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "400": {
      "description": "Invalid request",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "402": {
      "description": "Insufficient credits",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "403": {
      "description": "Write access required",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "404": {
      "description": "Source or collection not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "409": {
      "description": "Request ID conflict or variant not approved",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "429": {
      "description": "Rate limited",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "500": {
      "description": "Internal error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "503": {
      "description": "Generation unavailable",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    }
  },
  "deprecated": true
}

POST/v1/assets/{id}/svgGenerate an SVG from a selected image or logo

Creates an editable vector derivative from this exact completed image, transparent image or sticker, attached to the same item. Uses the highest-quality configured vector model. Costs 30 credits; failures refund charged credits. Async: poll the returned job URL. Generation can take several minutes. Reuse request_id to retry the same submission without another charge; a new ID starts a new paid attempt. SVG details can differ from the source. Published logo items expose the newest completed vector at logos.svg in cdn-export. Download via the returned asset file_url or cdn_url.

Select Masko-API-Version: 2026-09-26 (or api_version=2026-09-26) for the canonical mascot contract shown first. Existing unversioned clients keep legacy collection fields. A mascot_id query filter also selects the canonical contract. Mixing identifier names returns 400.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

Idempotency-Keyheader

string

Masko-API-Versionheader

Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract.

string · 2026-09-26, legacy

api_versionquery

Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree.

string · 2026-09-26, legacy

Request body (required)

application/json

request_idstring · uuid · required

Idempotency ID. Reuse for retries of this source; use a new ID only for a new paid generation.

Responses

202 SVG job receipt

application/json

dataobject · required

Nested fields

job_idstring · uuid · required

asset_idsobject · required

Nested fields

svgstring · uuid · required

statusstring · required

Values: "pending", "processing", "completed", "failed"

estimated_costnumber · required

poll_urlstring · required

400 Invalid request

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

402 Insufficient credits

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Write access required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Source or collection not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Request ID conflict or variant not approved

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

429 Rate limited

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

500 Internal error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

503 Generation unavailable

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "operationId": "generateAssetSvg",
  "tags": [
    "Assets"
  ],
  "summary": "Generate an SVG from a selected image or logo",
  "description": "Creates an editable vector derivative from this exact completed image, transparent image or sticker, attached to the same item. Uses the highest-quality configured vector model. Costs 30 credits; failures refund charged credits. Async: poll the returned job URL. Generation can take several minutes. Reuse request_id to retry the same submission without another charge; a new ID starts a new paid attempt. SVG details can differ from the source. Published logo items expose the newest completed vector at logos.svg in cdn-export. Download via the returned asset file_url or cdn_url.\n\nSelect Masko-API-Version: 2026-09-26 (or api_version=2026-09-26) for the canonical mascot contract shown first. Existing unversioned clients keep legacy collection fields. A mascot_id query filter also selects the canonical contract. Mixing identifier names returns 400.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.",
      "schema": {
        "type": "string",
        "maxLength": 255
      }
    },
    {
      "in": "header",
      "name": "Masko-API-Version",
      "required": false,
      "schema": {
        "type": "string",
        "enum": [
          "2026-09-26",
          "legacy"
        ]
      },
      "description": "Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract."
    },
    {
      "in": "query",
      "name": "api_version",
      "required": false,
      "schema": {
        "type": "string",
        "enum": [
          "2026-09-26",
          "legacy"
        ]
      },
      "description": "Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "request_id": {
              "type": "string",
              "format": "uuid",
              "description": "Idempotency ID. Reuse for retries of this source; use a new ID only for a new paid generation."
            }
          },
          "required": [
            "request_id"
          ],
          "additionalProperties": false
        }
      }
    }
  },
  "responses": {
    "202": {
      "description": "SVG job receipt",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "job_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "asset_ids": {
                    "type": "object",
                    "properties": {
                      "svg": {
                        "type": "string",
                        "format": "uuid"
                      }
                    },
                    "required": [
                      "svg"
                    ]
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "pending",
                      "processing",
                      "completed",
                      "failed"
                    ]
                  },
                  "estimated_cost": {
                    "type": "number"
                  },
                  "poll_url": {
                    "type": "string"
                  }
                },
                "required": [
                  "job_id",
                  "asset_ids",
                  "status",
                  "estimated_cost",
                  "poll_url"
                ]
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Invalid request",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "402": {
      "description": "Insufficient credits",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "403": {
      "description": "Write access required",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "404": {
      "description": "Source or collection not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "409": {
      "description": "Request ID conflict or variant not approved",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "429": {
      "description": "Rate limited",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "500": {
      "description": "Internal error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "503": {
      "description": "Generation unavailable",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    }
  }
}

POST/v1/assets/{id}/exportsExport one image, video or chat sticker

Creates a derivative of this exact completed source asset. Create a library sticker first with POST /v1/assets/{animation_id}/sticker to prepare all four platforms. Its sticker_animation asset ID can then request an individual platform export here. Image sources: image, transparent_image or sticker_image; formats PNG/WebP. Size is the maximum image dimension (32–2048), preserving aspect ratio and alpha without upscaling. Video sources: video/webm/hevc with an existing background-removal job; size is width (32–1920). Video formats: webm, hevc, prores (ProRes 4444 MOV with alpha for video editing), stacked_video, gif, animated_webp (transparent, looping, lossy), lottie, dotlottie, png_sequence, mkpk. Omit size for original. mkpk is one animation as a .mkpk version 1 pack for ESP32 boards running the Masko SDK (64-byte header, frame index, baseline 4:2:0 JPEG frames on 512-byte boundaries): size is required and is the exact frame width, a multiple of 16 from 32 to 1024 and never wider than the animation; mkpk.screen_width and mkpk.screen_height (together) centre the frames on that screen, mkpk.fps defaults to 24, mkpk.quality to 75 and mkpk.background_color to black. Nothing is resized, cropped differently or reversed for you: reversed animations are refused because the player reverses the forward pack. The metadata of a completed export carries bytes, sha256, frame_count and the frame position x and y; public_url is a stable CDN URL that serves byte ranges when the mascot is published. For an animated chat sticker set sticker_profile: telegram (WebM), whatsapp (animated WebP), wechat (GIF) or discord (APNG). A name without -v1 means the current version; format may be omitted, and if sent must be the file type of that profile. Formats sticker-telegram-v1, sticker-whatsapp-v1, sticker-wechat-v1 and sticker-discord-v1 do the same. Each profile determines codec, dimensions and duration and keeps 10% file-size headroom. Omit size. apng exists only as the Discord sticker. Only validated results become downloadable. No generation credits. Reuses a pending/completed export for the same source/format/size; force requests a new file without changing old URLs. Poll the job, then GET this export list for signed downloads. Accepts Idempotency-Key.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

Idempotency-Keyheader

string

Masko-API-Versionheader

Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract.

string · 2026-09-26, legacy

api_versionquery

Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree.

string · 2026-09-26, legacy

Request body (required)

application/json

formatstring

File to make. Images: png, webp. Animations: webm, hevc, prores, stacked_video, gif, animated_webp (transparent, looping), lottie, dotlottie, png_sequence, mkpk; apng only as a Discord sticker. Add sticker_profile for a chat sticker. sticker-telegram-v1, sticker-whatsapp-v1, sticker-wechat-v1 and sticker-discord-v1 are the same as that sticker_profile alone.

Values: "png", "webp", "webm", "hevc", "prores", "stacked_video", "gif", "animated_webp", "apng", "lottie", "dotlottie", "png_sequence", "mkpk", "sticker-telegram-v1", "sticker-whatsapp-v1", "sticker-wechat-v1", "sticker-discord-v1"

sticker_profilestring

Makes a chat sticker for that app, which sets its file type, size, length and file-size limit: telegram (WebM, 512 px, 3 s), whatsapp (animated WebP, 512 px, 10 s), wechat (GIF, 240 px, 3 s) or discord (APNG, 320 px, 5 s). Without -v1 it means the current version. Format can be omitted; size must be.

Values: "telegram-v1", "whatsapp-v1", "wechat-v1", "discord-v1", "telegram", "whatsapp", "wechat", "discord"

sizeinteger

Maximum image dimension, or video width. Omit for original size. Videos support up to 1920. Required for mkpk: the exact frame width, a multiple of 16 up to 1024. Omit for stickers.

Range: 32 to 2048

mkpkobject

Settings for format mkpk: screen, frames per second, JPEG quality and background colour.

Nested fields

screen_widthinteger

Screen the pack is made for; the frames are centred on it. Set with screen_height. Defaults to the frame size.

Range: 16 to 1024

screen_heightinteger

Range: 16 to 1024

fpsinteger

Frames per second. Defaults to 24.

Range: 1 to 60

qualityinteger

JPEG quality from 1 to 100. Defaults to 75.

Range: 1 to 100

background_colorstring

Colour behind the mascot, as #RRGGBB. Defaults to black.

Pattern: ^#[0-9a-fA-F]{6}$

forceboolean

Make a new file even when a matching export exists.

Default: false

Responses

200 Completed reusable export

application/json

dataobject · required

Nested fields

idstring · uuid · required

source_asset_idstring · uuid · required

formatstring · required

sizenumber · nullable · required

mkpkobject

Complete settings of an mkpk export.

Nested fields

screen_widthnumber · required

screen_heightnumber · required

fpsnumber · required

qualitynumber · required

background_colorstring · required

job_idstring · uuid · required

asset_idstring · uuid · required

statusstring · required

Values: "pending", "processing", "completed", "failed"

errorstring · nullable · required

file_urlstring · nullable · required

public_urlstring · nullable · required

metadataobject · nullable

sticker_profilestring

poster_urlstring · nullable

poll_urlstring · required

202 Export queued

application/json

dataobject · required

Nested fields

idstring · uuid · required

source_asset_idstring · uuid · required

formatstring · required

sizenumber · nullable · required

mkpkobject

Complete settings of an mkpk export.

Nested fields

screen_widthnumber · required

screen_heightnumber · required

fpsnumber · required

qualitynumber · required

background_colorstring · required

job_idstring · uuid · required

asset_idstring · uuid · required

statusstring · required

Values: "pending", "processing", "completed", "failed"

errorstring · nullable · required

file_urlstring · nullable · required

public_urlstring · nullable · required

metadataobject · nullable

sticker_profilestring

poster_urlstring · nullable

poll_urlstring · required

400 Request failed

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Request failed

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Request failed

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Request failed

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Request failed

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

429 Request failed

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

500 Request failed

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

503 Request failed

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "operationId": "createAssetExport",
  "tags": [
    "Assets"
  ],
  "summary": "Export one image, video or chat sticker",
  "description": "Creates a derivative of this exact completed source asset. Create a library sticker first with POST /v1/assets/{animation_id}/sticker to prepare all four platforms. Its sticker_animation asset ID can then request an individual platform export here. Image sources: image, transparent_image or sticker_image; formats PNG/WebP. Size is the maximum image dimension (32–2048), preserving aspect ratio and alpha without upscaling. Video sources: video/webm/hevc with an existing background-removal job; size is width (32–1920). Video formats: webm, hevc, prores (ProRes 4444 MOV with alpha for video editing), stacked_video, gif, animated_webp (transparent, looping, lossy), lottie, dotlottie, png_sequence, mkpk. Omit size for original. mkpk is one animation as a .mkpk version 1 pack for ESP32 boards running the Masko SDK (64-byte header, frame index, baseline 4:2:0 JPEG frames on 512-byte boundaries): size is required and is the exact frame width, a multiple of 16 from 32 to 1024 and never wider than the animation; mkpk.screen_width and mkpk.screen_height (together) centre the frames on that screen, mkpk.fps defaults to 24, mkpk.quality to 75 and mkpk.background_color to black. Nothing is resized, cropped differently or reversed for you: reversed animations are refused because the player reverses the forward pack. The metadata of a completed export carries bytes, sha256, frame_count and the frame position x and y; public_url is a stable CDN URL that serves byte ranges when the mascot is published. For an animated chat sticker set sticker_profile: telegram (WebM), whatsapp (animated WebP), wechat (GIF) or discord (APNG). A name without -v1 means the current version; format may be omitted, and if sent must be the file type of that profile. Formats sticker-telegram-v1, sticker-whatsapp-v1, sticker-wechat-v1 and sticker-discord-v1 do the same. Each profile determines codec, dimensions and duration and keeps 10% file-size headroom. Omit size. apng exists only as the Discord sticker. Only validated results become downloadable. No generation credits. Reuses a pending/completed export for the same source/format/size; force requests a new file without changing old URLs. Poll the job, then GET this export list for signed downloads. Accepts Idempotency-Key.\n\nSelect Masko-API-Version: 2026-09-26 (or api_version=2026-09-26) for the canonical mascot contract shown first. Existing unversioned clients keep legacy collection fields. A mascot_id query filter also selects the canonical contract. Mixing identifier names returns 400.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.",
      "schema": {
        "type": "string",
        "maxLength": 255
      }
    },
    {
      "in": "header",
      "name": "Masko-API-Version",
      "required": false,
      "schema": {
        "type": "string",
        "enum": [
          "2026-09-26",
          "legacy"
        ]
      },
      "description": "Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract."
    },
    {
      "in": "query",
      "name": "api_version",
      "required": false,
      "schema": {
        "type": "string",
        "enum": [
          "2026-09-26",
          "legacy"
        ]
      },
      "description": "Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "format": {
              "type": "string",
              "enum": [
                "png",
                "webp",
                "webm",
                "hevc",
                "prores",
                "stacked_video",
                "gif",
                "animated_webp",
                "apng",
                "lottie",
                "dotlottie",
                "png_sequence",
                "mkpk",
                "sticker-telegram-v1",
                "sticker-whatsapp-v1",
                "sticker-wechat-v1",
                "sticker-discord-v1"
              ],
              "description": "File to make. Images: png, webp. Animations: webm, hevc, prores, stacked_video, gif, animated_webp (transparent, looping), lottie, dotlottie, png_sequence, mkpk; apng only as a Discord sticker. Add sticker_profile for a chat sticker. sticker-telegram-v1, sticker-whatsapp-v1, sticker-wechat-v1 and sticker-discord-v1 are the same as that sticker_profile alone."
            },
            "sticker_profile": {
              "type": "string",
              "enum": [
                "telegram-v1",
                "whatsapp-v1",
                "wechat-v1",
                "discord-v1",
                "telegram",
                "whatsapp",
                "wechat",
                "discord"
              ],
              "description": "Makes a chat sticker for that app, which sets its file type, size, length and file-size limit: telegram (WebM, 512 px, 3 s), whatsapp (animated WebP, 512 px, 10 s), wechat (GIF, 240 px, 3 s) or discord (APNG, 320 px, 5 s). Without -v1 it means the current version. Format can be omitted; size must be."
            },
            "size": {
              "type": "integer",
              "minimum": 32,
              "maximum": 2048,
              "description": "Maximum image dimension, or video width. Omit for original size. Videos support up to 1920. Required for mkpk: the exact frame width, a multiple of 16 up to 1024. Omit for stickers."
            },
            "mkpk": {
              "type": "object",
              "properties": {
                "screen_width": {
                  "type": "integer",
                  "minimum": 16,
                  "maximum": 1024,
                  "description": "Screen the pack is made for; the frames are centred on it. Set with screen_height. Defaults to the frame size."
                },
                "screen_height": {
                  "type": "integer",
                  "minimum": 16,
                  "maximum": 1024
                },
                "fps": {
                  "type": "integer",
                  "minimum": 1,
                  "maximum": 60,
                  "description": "Frames per second. Defaults to 24."
                },
                "quality": {
                  "type": "integer",
                  "minimum": 1,
                  "maximum": 100,
                  "description": "JPEG quality from 1 to 100. Defaults to 75."
                },
                "background_color": {
                  "type": "string",
                  "pattern": "^#[0-9a-fA-F]{6}$",
                  "description": "Colour behind the mascot, as #RRGGBB. Defaults to black."
                }
              },
              "additionalProperties": false,
              "description": "Settings for format mkpk: screen, frames per second, JPEG quality and background colour."
            },
            "force": {
              "type": "boolean",
              "default": false,
              "description": "Make a new file even when a matching export exists."
            }
          },
          "additionalProperties": false
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Completed reusable export",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "source_asset_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "format": {
                    "type": "string"
                  },
                  "size": {
                    "type": "number",
                    "nullable": true
                  },
                  "mkpk": {
                    "type": "object",
                    "properties": {
                      "screen_width": {
                        "type": "number"
                      },
                      "screen_height": {
                        "type": "number"
                      },
                      "fps": {
                        "type": "number"
                      },
                      "quality": {
                        "type": "number"
                      },
                      "background_color": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "screen_width",
                      "screen_height",
                      "fps",
                      "quality",
                      "background_color"
                    ],
                    "description": "Complete settings of an mkpk export."
                  },
                  "job_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "asset_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "pending",
                      "processing",
                      "completed",
                      "failed"
                    ]
                  },
                  "error": {
                    "type": "string",
                    "nullable": true
                  },
                  "file_url": {
                    "type": "string",
                    "nullable": true
                  },
                  "public_url": {
                    "type": "string",
                    "nullable": true
                  },
                  "metadata": {
                    "nullable": true
                  },
                  "sticker_profile": {
                    "type": "string"
                  },
                  "poster_url": {
                    "type": "string",
                    "nullable": true
                  },
                  "poll_url": {
                    "type": "string"
                  }
                },
                "required": [
                  "id",
                  "source_asset_id",
                  "format",
                  "size",
                  "job_id",
                  "asset_id",
                  "status",
                  "error",
                  "file_url",
                  "public_url",
                  "poll_url"
                ]
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "202": {
      "description": "Export queued",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "source_asset_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "format": {
                    "type": "string"
                  },
                  "size": {
                    "type": "number",
                    "nullable": true
                  },
                  "mkpk": {
                    "type": "object",
                    "properties": {
                      "screen_width": {
                        "type": "number"
                      },
                      "screen_height": {
                        "type": "number"
                      },
                      "fps": {
                        "type": "number"
                      },
                      "quality": {
                        "type": "number"
                      },
                      "background_color": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "screen_width",
                      "screen_height",
                      "fps",
                      "quality",
                      "background_color"
                    ],
                    "description": "Complete settings of an mkpk export."
                  },
                  "job_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "asset_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "pending",
                      "processing",
                      "completed",
                      "failed"
                    ]
                  },
                  "error": {
                    "type": "string",
                    "nullable": true
                  },
                  "file_url": {
                    "type": "string",
                    "nullable": true
                  },
                  "public_url": {
                    "type": "string",
                    "nullable": true
                  },
                  "metadata": {
                    "nullable": true
                  },
                  "sticker_profile": {
                    "type": "string"
                  },
                  "poster_url": {
                    "type": "string",
                    "nullable": true
                  },
                  "poll_url": {
                    "type": "string"
                  }
                },
                "required": [
                  "id",
                  "source_asset_id",
                  "format",
                  "size",
                  "job_id",
                  "asset_id",
                  "status",
                  "error",
                  "file_url",
                  "public_url",
                  "poll_url"
                ]
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Request failed",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "401": {
      "description": "Request failed",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "403": {
      "description": "Request failed",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "404": {
      "description": "Request failed",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "409": {
      "description": "Request failed",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "429": {
      "description": "Request failed",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "500": {
      "description": "Request failed",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "503": {
      "description": "Request failed",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    }
  }
}

GET/v1/assets/{id}/exportsList exports for one asset

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

Masko-API-Versionheader

Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract.

string · 2026-09-26, legacy

api_versionquery

Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree.

string · 2026-09-26, legacy

Responses

200 Current export files and jobs

application/json

dataarray · required

Nested fields

idstring · uuid · required

source_asset_idstring · uuid · required

formatstring · required

sizenumber · nullable · required

mkpkobject

Complete settings of an mkpk export.

Nested fields

screen_widthnumber · required

screen_heightnumber · required

fpsnumber · required

qualitynumber · required

background_colorstring · required

job_idstring · uuid · required

asset_idstring · uuid · required

statusstring · required

Values: "pending", "processing", "completed", "failed"

errorstring · nullable · required

file_urlstring · nullable · required

public_urlstring · nullable · required

metadataobject · nullable

sticker_profilestring

poster_urlstring · nullable

poll_urlstring · required

400 Request failed

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Request failed

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Request failed

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Request failed

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Request failed

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

429 Request failed

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

500 Request failed

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

503 Request failed

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "operationId": "listAssetExports",
  "tags": [
    "Assets"
  ],
  "summary": "List exports for one asset",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "in": "header",
      "name": "Masko-API-Version",
      "required": false,
      "schema": {
        "type": "string",
        "enum": [
          "2026-09-26",
          "legacy"
        ]
      },
      "description": "Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract."
    },
    {
      "in": "query",
      "name": "api_version",
      "required": false,
      "schema": {
        "type": "string",
        "enum": [
          "2026-09-26",
          "legacy"
        ]
      },
      "description": "Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree."
    }
  ],
  "responses": {
    "200": {
      "description": "Current export files and jobs",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "source_asset_id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "format": {
                      "type": "string"
                    },
                    "size": {
                      "type": "number",
                      "nullable": true
                    },
                    "mkpk": {
                      "type": "object",
                      "properties": {
                        "screen_width": {
                          "type": "number"
                        },
                        "screen_height": {
                          "type": "number"
                        },
                        "fps": {
                          "type": "number"
                        },
                        "quality": {
                          "type": "number"
                        },
                        "background_color": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "screen_width",
                        "screen_height",
                        "fps",
                        "quality",
                        "background_color"
                      ],
                      "description": "Complete settings of an mkpk export."
                    },
                    "job_id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "asset_id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "pending",
                        "processing",
                        "completed",
                        "failed"
                      ]
                    },
                    "error": {
                      "type": "string",
                      "nullable": true
                    },
                    "file_url": {
                      "type": "string",
                      "nullable": true
                    },
                    "public_url": {
                      "type": "string",
                      "nullable": true
                    },
                    "metadata": {
                      "nullable": true
                    },
                    "sticker_profile": {
                      "type": "string"
                    },
                    "poster_url": {
                      "type": "string",
                      "nullable": true
                    },
                    "poll_url": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "id",
                    "source_asset_id",
                    "format",
                    "size",
                    "job_id",
                    "asset_id",
                    "status",
                    "error",
                    "file_url",
                    "public_url",
                    "poll_url"
                  ]
                }
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Request failed",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "401": {
      "description": "Request failed",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "403": {
      "description": "Request failed",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "404": {
      "description": "Request failed",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "409": {
      "description": "Request failed",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "429": {
      "description": "Request failed",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "500": {
      "description": "Request failed",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "503": {
      "description": "Request failed",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    }
  },
  "description": "\n\nSelect Masko-API-Version: 2026-09-26 (or api_version=2026-09-26) for the canonical mascot contract shown first. Existing unversioned clients keep legacy collection fields. A mascot_id query filter also selects the canonical contract. Mixing identifier names returns 400."
}

POST/v1/mascots/{id}/exportsGenerate missing image and video exports

Uses the mascot’s saved image_exports, prores_exports, mkpk_exports and animation_sizes settings. ProRes is opt-in and exports one original-delivery-size MOV per video. mkpk_exports is opt-in and exports one .mkpk pack per forward animation, all with the same width and settings. Disabled sections are skipped. Creates an asynchronous batch job which schedules individual export jobs. Batch completion means scheduling finished, not that every file is ready. Existing in-flight work is reused; force regenerates completed exports. No settings change and no generation credit charge.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

Idempotency-Keyheader

string

Request body (required)

application/json

typesarray

Default: ["image","video"]

Items: 1 to 2

Nested fields

string · image, video

forceboolean

Default: false

Responses

202 Batch job receipt

application/json

dataobject · required

Nested fields

job_idstring · uuid · required

poll_urlstring · required

400 Request failed

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Request failed

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Request failed

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Request failed

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Request failed

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

429 Request failed

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

500 Request failed

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

503 Request failed

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "operationId": "backfillMascotExports",
  "tags": [
    "Collections"
  ],
  "summary": "Generate missing image and video exports",
  "description": "Uses the mascot’s saved image_exports, prores_exports, mkpk_exports and animation_sizes settings. ProRes is opt-in and exports one original-delivery-size MOV per video. mkpk_exports is opt-in and exports one .mkpk pack per forward animation, all with the same width and settings. Disabled sections are skipped. Creates an asynchronous batch job which schedules individual export jobs. Batch completion means scheduling finished, not that every file is ready. Existing in-flight work is reused; force regenerates completed exports. No settings change and no generation credit charge.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.",
      "schema": {
        "type": "string",
        "maxLength": 255
      }
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "types": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "image",
                  "video"
                ]
              },
              "minItems": 1,
              "maxItems": 2,
              "default": [
                "image",
                "video"
              ]
            },
            "force": {
              "type": "boolean",
              "default": false
            }
          },
          "additionalProperties": false
        }
      }
    }
  },
  "responses": {
    "202": {
      "description": "Batch job receipt",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "job_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "poll_url": {
                    "type": "string"
                  }
                },
                "required": [
                  "job_id",
                  "poll_url"
                ]
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Request failed",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "401": {
      "description": "Request failed",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "403": {
      "description": "Request failed",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "404": {
      "description": "Request failed",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "409": {
      "description": "Request failed",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "429": {
      "description": "Request failed",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "500": {
      "description": "Request failed",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "503": {
      "description": "Request failed",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    }
  },
  "x-masko-api-version": "2026-09-26"
}

POST/v1/projects/{id}/export-settingsApply export settings to project or folder mascots

Merges supplied settings into mascots currently in the selected project or folder. Does not establish inherited defaults for future mascots. Image settings apply to future completed assets; apply_to_existing explicitly queues backfill jobs for existing assets. Preserves omitted settings.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

Idempotency-Keyheader

string

Masko-API-Versionheader

Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract.

string · 2026-09-26, legacy

api_versionquery

Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree.

string · 2026-09-26, legacy

Request body (required)

application/json

publish_paramsobject · required

Nested fields

image_exportsobject

Nested fields

enabledboolean · required

sourcesarray · required

Items: 1 to 3

Nested fields

string · original, transparent, sticker

formatsarray · required

Items: 1 to 2

Nested fields

string · png, webp

sizesarray · required

Items: 1 to 5

Nested fields

integer

prores_exportsobject

Automatically create original-delivery-size ProRes 4444 MOV files with alpha after transparent animations finish. Disabled by default.

Nested fields

enabledboolean · required

mkpk_exportsobject

Automatically create one .mkpk pack (ESP32 Masko SDK) per forward animation once its transparent video exists, all with the same width and settings. Disabled by default.

Nested fields

screen_widthinteger

Screen the pack is made for; the frames are centred on it. Set with screen_height. Defaults to the frame size.

Range: 16 to 1024

screen_heightinteger

Range: 16 to 1024

fpsinteger

Frames per second. Defaults to 24.

Range: 1 to 60

qualityinteger

JPEG quality from 1 to 100. Defaults to 75.

Range: 1 to 100

background_colorstring

Colour behind the mascot, as #RRGGBB. Defaults to black.

Pattern: ^#[0-9a-fA-F]{6}$

enabledboolean · required

sizeinteger

Frame width in pixels, a multiple of 16. Required when enabled.

Range: 32 to 1024

animation_sizesobject

Nested fields

enabledboolean · required

sizesarray · required

Items: 0 to 6

Nested fields

integer

custom_sizeinteger

Range: 32 to 1920

folder_idstring · uuid

apply_to_existingboolean

Default: false

Responses

200 Applied settings and optional backfill jobs

application/json

dataobject · required

Nested fields

updated_countnumber · required

jobsarray · required

Nested fields

job_idstring · uuid · required

poll_urlstring · required

400 Request failed

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Request failed

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Request failed

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Request failed

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Request failed

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

429 Request failed

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

500 Request failed

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

503 Request failed

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "operationId": "applyProjectExportSettings",
  "tags": [
    "Projects"
  ],
  "summary": "Apply export settings to project or folder mascots",
  "description": "Merges supplied settings into mascots currently in the selected project or folder. Does not establish inherited defaults for future mascots. Image settings apply to future completed assets; apply_to_existing explicitly queues backfill jobs for existing assets. Preserves omitted settings.\n\nSelect Masko-API-Version: 2026-09-26 (or api_version=2026-09-26) for the canonical mascot contract shown first. Existing unversioned clients keep legacy collection fields. A mascot_id query filter also selects the canonical contract. Mixing identifier names returns 400.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.",
      "schema": {
        "type": "string",
        "maxLength": 255
      }
    },
    {
      "in": "header",
      "name": "Masko-API-Version",
      "required": false,
      "schema": {
        "type": "string",
        "enum": [
          "2026-09-26",
          "legacy"
        ]
      },
      "description": "Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract."
    },
    {
      "in": "query",
      "name": "api_version",
      "required": false,
      "schema": {
        "type": "string",
        "enum": [
          "2026-09-26",
          "legacy"
        ]
      },
      "description": "Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "publish_params": {
              "type": "object",
              "properties": {
                "image_exports": {
                  "type": "object",
                  "properties": {
                    "enabled": {
                      "type": "boolean"
                    },
                    "sources": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "enum": [
                          "original",
                          "transparent",
                          "sticker"
                        ]
                      },
                      "minItems": 1,
                      "maxItems": 3
                    },
                    "formats": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "enum": [
                          "png",
                          "webp"
                        ]
                      },
                      "minItems": 1,
                      "maxItems": 2
                    },
                    "sizes": {
                      "type": "array",
                      "items": {
                        "type": "integer",
                        "minimum": 32,
                        "maximum": 2048
                      },
                      "minItems": 1,
                      "maxItems": 5
                    }
                  },
                  "required": [
                    "enabled",
                    "sources",
                    "formats",
                    "sizes"
                  ],
                  "additionalProperties": false
                },
                "prores_exports": {
                  "type": "object",
                  "properties": {
                    "enabled": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "enabled"
                  ],
                  "additionalProperties": false,
                  "description": "Automatically create original-delivery-size ProRes 4444 MOV files with alpha after transparent animations finish. Disabled by default."
                },
                "mkpk_exports": {
                  "type": "object",
                  "properties": {
                    "screen_width": {
                      "type": "integer",
                      "minimum": 16,
                      "maximum": 1024,
                      "description": "Screen the pack is made for; the frames are centred on it. Set with screen_height. Defaults to the frame size."
                    },
                    "screen_height": {
                      "type": "integer",
                      "minimum": 16,
                      "maximum": 1024
                    },
                    "fps": {
                      "type": "integer",
                      "minimum": 1,
                      "maximum": 60,
                      "description": "Frames per second. Defaults to 24."
                    },
                    "quality": {
                      "type": "integer",
                      "minimum": 1,
                      "maximum": 100,
                      "description": "JPEG quality from 1 to 100. Defaults to 75."
                    },
                    "background_color": {
                      "type": "string",
                      "pattern": "^#[0-9a-fA-F]{6}$",
                      "description": "Colour behind the mascot, as #RRGGBB. Defaults to black."
                    },
                    "enabled": {
                      "type": "boolean"
                    },
                    "size": {
                      "type": "integer",
                      "minimum": 32,
                      "maximum": 1024,
                      "description": "Frame width in pixels, a multiple of 16. Required when enabled."
                    }
                  },
                  "required": [
                    "enabled"
                  ],
                  "additionalProperties": false,
                  "description": "Automatically create one .mkpk pack (ESP32 Masko SDK) per forward animation once its transparent video exists, all with the same width and settings. Disabled by default."
                },
                "animation_sizes": {
                  "type": "object",
                  "properties": {
                    "enabled": {
                      "type": "boolean"
                    },
                    "sizes": {
                      "type": "array",
                      "items": {
                        "type": "integer",
                        "minimum": 32,
                        "maximum": 1920
                      },
                      "maxItems": 6
                    },
                    "custom_size": {
                      "type": "integer",
                      "minimum": 32,
                      "maximum": 1920
                    }
                  },
                  "required": [
                    "enabled",
                    "sizes"
                  ],
                  "additionalProperties": false
                }
              },
              "additionalProperties": false
            },
            "folder_id": {
              "type": "string",
              "format": "uuid"
            },
            "apply_to_existing": {
              "type": "boolean",
              "default": false
            }
          },
          "required": [
            "publish_params"
          ],
          "additionalProperties": false
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Applied settings and optional backfill jobs",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "updated_count": {
                    "type": "number"
                  },
                  "jobs": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "job_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "poll_url": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "job_id",
                        "poll_url"
                      ]
                    }
                  }
                },
                "required": [
                  "updated_count",
                  "jobs"
                ]
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Request failed",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "401": {
      "description": "Request failed",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "403": {
      "description": "Request failed",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "404": {
      "description": "Request failed",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "409": {
      "description": "Request failed",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "429": {
      "description": "Request failed",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "500": {
      "description": "Request failed",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "503": {
      "description": "Request failed",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    }
  }
}

POST/v1/animationsAnimate an uploaded image

Animate a completed image without generating another pose. Send either mascot_id to reuse an existing mascot, or create_mascot: {project_id, name?} to explicitly create one from an unattached upload in the same request. Omit create_mascot.name for an AI-chosen character name; no character description is generated. Returns mascot_id, mascot_name and mascot_created alongside the normal job receipt. Reuse mascot_id for subsequent animations to avoid creating extra mascots. Non-square inputs are center-cropped to square before animation; source_image_crop overrides framing. Originals are preserved. Only animation credits are charged: Standard (default) 2/sec, Premium 6/sec, default 5 seconds. Use Idempotency-Key to retry the complete operation without creating another mascot or job. If generation fails after mascot creation, error.details.mascot_id identifies the saved mascot; reuse it in a corrected request with a new key. This endpoint uses the canonical mascot API contract automatically.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

Idempotency-Keyheader

string

Request body (required)

application/json

source_image_asset_idstring · uuid · required

Completed image to animate. For a new mascot, use an unattached image from POST /v1/upload.

source_image_cropobject

Square crop in pixels after EXIF orientation. Omit for a centered square crop. The original is preserved.

Nested fields

xinteger · required

Range: 0 to unbounded

yinteger · required

Range: 0 to unbounded

widthinteger · required

Range: 0 to unbounded

heightinteger · required

Range: 0 to unbounded

mascot_idstring · uuid

Save under this existing mascot. Reuse the ID returned by your first request.

create_mascotobject

Explicitly create a new mascot in this project. Send this or mascot_id, never both.

Nested fields

project_idstring · uuid · required

namestring

Optional mascot name. When omitted, AI chooses a short name from the image. No character description is generated.

Length: 1 to 80 characters

variant_idstring · uuid

namestring

Animation action name, separate from the mascot name.

Default: "Animation"

Length: 1 to 100 characters

animation_promptstring · required

Length: 1 to 5000 characters

animation_modelstring

Standard: 2 credits/sec, 2–15 seconds. Premium: 6 credits/sec, 4–30 seconds. Defaults to Standard.

Values: "standard", "premium"

Default: "standard"

durationinteger

Default: 5

Range: 2 to 30

loopboolean

Default: true

Responses

202 Animation accepted

application/json

dataobject · required

Nested fields

GenerateAsyncData

job_idstring · uuid · required

statusstring · required

Values: "pending", "processing", "completed", "failed"

typestring · required

Values: "image", "animation", "edit", "logo", "reverse"

item_idstring · uuid · required

item_namestring · required

estimated_costnumber · required

asset_idsobject

urlsobject

estimateobject

Talking animations only.

Nested fields

speech_secondsnumber · required

Estimated length of the spoken line.

durationinteger · required

Most likely video length in seconds.

max_durationinteger · required

The longest the video could need; the charge is based on it.

creditsinteger · required

Charged now: max_duration at 2 credits per second. Unused seconds are refunded once the voice is recorded.

too_longboolean · required

scriptstring

Talking animations only: the line with its movements, as performed.

poll_urlstring · required

Option 2

mascot_idstring · uuid · required

mascot_namestring · required

mascot_createdboolean · required

400 Request failed

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Request failed

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

402 Request failed

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Request failed

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Request failed

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Request failed

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

429 Request failed

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

500 Request failed

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

503 Request failed

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "operationId": "createAnimation",
  "tags": [
    "Generate"
  ],
  "summary": "Animate an uploaded image",
  "description": "Animate a completed image without generating another pose. Send either mascot_id to reuse an existing mascot, or create_mascot: {project_id, name?} to explicitly create one from an unattached upload in the same request. Omit create_mascot.name for an AI-chosen character name; no character description is generated. Returns mascot_id, mascot_name and mascot_created alongside the normal job receipt. Reuse mascot_id for subsequent animations to avoid creating extra mascots. Non-square inputs are center-cropped to square before animation; source_image_crop overrides framing. Originals are preserved. Only animation credits are charged: Standard (default) 2/sec, Premium 6/sec, default 5 seconds. Use Idempotency-Key to retry the complete operation without creating another mascot or job. If generation fails after mascot creation, error.details.mascot_id identifies the saved mascot; reuse it in a corrected request with a new key. This endpoint uses the canonical mascot API contract automatically.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/CreateAnimationBody"
        }
      }
    }
  },
  "responses": {
    "202": {
      "description": "Animation accepted",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CreateAnimationResponse"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Request failed",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "401": {
      "description": "Request failed",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "402": {
      "description": "Request failed",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "403": {
      "description": "Request failed",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "404": {
      "description": "Request failed",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "409": {
      "description": "Request failed",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "429": {
      "description": "Request failed",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "500": {
      "description": "Request failed",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "503": {
      "description": "Request failed",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    }
  },
  "parameters": [
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.",
      "schema": {
        "type": "string",
        "maxLength": 255
      }
    }
  ],
  "x-masko-api-version": "2026-09-26"
}

POST/v1/mascots/from-brand-bookCreate a mascot from a brand book

One call that turns a brand book into a mascot. Send the brand book as public links (a PDF up to 50 MB, or PNG, JPEG or WebP pages up to 10 MB each) or images from POST /v1/upload, at most 30 pages in total. The job reads the brand book for free, generates every mascot view and prop it finds as a clean image for 1 credit each (at most 5 views and 12 props, so at most 17 credits), then creates the mascot in project_id with the views as labeled references and the description, colors, style, don'ts and props filled in. Poll GET /v1/jobs/{job_id}: step reports progress, and a completed job returns result.mascot_id with what it cost. Nothing is charged when the brand book has no mascot, costs more than max_credits, or the balance is short; each image that fails is refunded. Takes about 2 to 4 minutes. Counts toward the limit of 15 brand book readings per day. Use Idempotency-Key to retry without starting a second job.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

Idempotency-Keyheader

string

Request body (required)

application/json

project_idstring · uuid · required

Project to create the mascot in.

filesarray · required

The brand book: one PDF, page images, or both, at most 30 pages in total, in reading order.

Items: 1 to 30

Nested fields

urlstring · uri

Public HTTP(S) link to a PDF (up to 50 MB) or a PNG, JPEG or WebP image (up to 10 MB). Downloaded server-side with public-address checks on every redirect.

Length: 0 to 2048 characters

asset_idstring · uuid

An image uploaded with POST /v1/upload, or a PDF sent to the signed upload_url that POST /v1/upload returns for content_type application/pdf.

namestring

File name shown in the mascot context.

Length: 1 to 200 characters

namestring

Mascot name. When omitted, the name written in the brand book is used.

Length: 1 to 80 characters

max_creditsinteger

Spending cap. Each view and prop generated costs 1 credit, at most 17 in total. When the brand book costs more, the job fails after the free reading and nothing is charged.

Range: 1 to 17

Responses

202 Brand book accepted

application/json

dataobject · required

Nested fields

job_idstring · uuid · required

statusstring · required

Values: "pending"

typestring · required

Values: "mascot_brand_book"

max_cost_creditsinteger · required

The most this job can charge.

poll_urlstring · required

400 Request failed

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Request failed

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

402 Request failed

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Request failed

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Request failed

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

429 Request failed

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

500 Request failed

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

503 Request failed

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "operationId": "createMascotFromBrandBook",
  "tags": [
    "Generate"
  ],
  "summary": "Create a mascot from a brand book",
  "description": "One call that turns a brand book into a mascot. Send the brand book as public links (a PDF up to 50 MB, or PNG, JPEG or WebP pages up to 10 MB each) or images from POST /v1/upload, at most 30 pages in total. The job reads the brand book for free, generates every mascot view and prop it finds as a clean image for 1 credit each (at most 5 views and 12 props, so at most 17 credits), then creates the mascot in project_id with the views as labeled references and the description, colors, style, don'ts and props filled in. Poll GET /v1/jobs/{job_id}: step reports progress, and a completed job returns result.mascot_id with what it cost. Nothing is charged when the brand book has no mascot, costs more than max_credits, or the balance is short; each image that fails is refunded. Takes about 2 to 4 minutes. Counts toward the limit of 15 brand book readings per day. Use Idempotency-Key to retry without starting a second job.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "project_id": {
              "type": "string",
              "format": "uuid",
              "description": "Project to create the mascot in."
            },
            "files": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string",
                    "maxLength": 2048,
                    "format": "uri",
                    "description": "Public HTTP(S) link to a PDF (up to 50 MB) or a PNG, JPEG or WebP image (up to 10 MB). Downloaded server-side with public-address checks on every redirect."
                  },
                  "asset_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "An image uploaded with POST /v1/upload, or a PDF sent to the signed upload_url that POST /v1/upload returns for content_type application/pdf."
                  },
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 200,
                    "description": "File name shown in the mascot context."
                  }
                },
                "additionalProperties": false
              },
              "minItems": 1,
              "maxItems": 30,
              "description": "The brand book: one PDF, page images, or both, at most 30 pages in total, in reading order."
            },
            "name": {
              "type": "string",
              "minLength": 1,
              "maxLength": 80,
              "description": "Mascot name. When omitted, the name written in the brand book is used."
            },
            "max_credits": {
              "type": "integer",
              "minimum": 1,
              "maximum": 17,
              "description": "Spending cap. Each view and prop generated costs 1 credit, at most 17 in total. When the brand book costs more, the job fails after the free reading and nothing is charged."
            }
          },
          "required": [
            "project_id",
            "files"
          ],
          "additionalProperties": false
        }
      }
    }
  },
  "responses": {
    "202": {
      "description": "Brand book accepted",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CreateMascotFromBrandBookResponse"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Request failed",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "401": {
      "description": "Request failed",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "402": {
      "description": "Request failed",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "403": {
      "description": "Request failed",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "404": {
      "description": "Request failed",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "429": {
      "description": "Request failed",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "500": {
      "description": "Request failed",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "503": {
      "description": "Request failed",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    }
  },
  "parameters": [
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.",
      "schema": {
        "type": "string",
        "maxLength": 255
      }
    }
  ],
  "x-masko-api-version": "2026-09-26"
}

GET/v1/collections/{id}/voiceGet the voice

Returns the voice the mascot speaks with in talking animations, or null. A marketplace copy speaks with its creator's voice (source creator). sample_url is a short recording.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

Responses

200 The voice, or null

application/json

dataobject · nullable · required

Nested fields

objectstring · required

Values: "voice"

namestring · required

descriptionstring · required

The words the voice was designed from.

sample_urlstring · uri · nullable · required

A short recording of the voice. Signed; fetch the voice again for a fresh link.

sourcestring · required

Whose voice this is: the mascot's own (original), the variant's own (variant), or the marketplace creator's (creator).

Values: "original", "variant", "creator"

created_atstring · required

400 Invalid request

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Authentication required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 The key lacks permission, or the voice belongs to the Marketplace creator

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Mascot, variant or sample not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 The variant is not approved yet, or the sample expired

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

429 Too many voice requests; retry later

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

502 Masko could not write the ideas or the adjustment; retry

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

503 The voice service is unavailable; retry later

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Voice"
  ],
  "summary": "Get the voice",
  "description": "Returns the voice the mascot speaks with in talking animations, or null. A marketplace copy speaks with its creator's voice (source creator). sample_url is a short recording.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    }
  ],
  "responses": {
    "200": {
      "description": "The voice, or null",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/Voice"
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "400": {
      "description": "Invalid request",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "401": {
      "description": "Authentication required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "403": {
      "description": "The key lacks permission, or the voice belongs to the Marketplace creator",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "404": {
      "description": "Mascot, variant or sample not found",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "409": {
      "description": "The variant is not approved yet, or the sample expired",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "429": {
      "description": "Too many voice requests; retry later",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "502": {
      "description": "Masko could not write the ideas or the adjustment; retry",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "503": {
      "description": "The voice service is unavailable; retry later",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  },
  "deprecated": true,
  "operationId": "legacyGetCollectionVoice"
}

PUT/v1/collections/{id}/voiceKeep a voice

Keeps one sample from POST /v1/collections/{id}/voice/samples as the voice of the mascot. It replaces the voice it had. Samples can be kept for 24 hours. No credit cost.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

Request body (required)

application/json

sample_idstring · uuid · required

A sample from POST .../voice/samples.

namestring

Defaults to "<name>'s voice".

Length: 1 to 80 characters

Responses

200 The kept voice

application/json

dataobject · nullable · required

Nested fields

objectstring · required

Values: "voice"

namestring · required

descriptionstring · required

The words the voice was designed from.

sample_urlstring · uri · nullable · required

A short recording of the voice. Signed; fetch the voice again for a fresh link.

sourcestring · required

Whose voice this is: the mascot's own (original), the variant's own (variant), or the marketplace creator's (creator).

Values: "original", "variant", "creator"

created_atstring · required

400 Invalid request

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Authentication required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 The key lacks permission, or the voice belongs to the Marketplace creator

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Mascot, variant or sample not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 The variant is not approved yet, or the sample expired

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

429 Too many voice requests; retry later

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

502 Masko could not write the ideas or the adjustment; retry

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

503 The voice service is unavailable; retry later

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Voice"
  ],
  "summary": "Keep a voice",
  "description": "Keeps one sample from POST /v1/collections/{id}/voice/samples as the voice of the mascot. It replaces the voice it had. Samples can be kept for 24 hours. No credit cost.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/KeepVoiceBody"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "The kept voice",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/Voice"
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "400": {
      "description": "Invalid request",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "401": {
      "description": "Authentication required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "403": {
      "description": "The key lacks permission, or the voice belongs to the Marketplace creator",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "404": {
      "description": "Mascot, variant or sample not found",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "409": {
      "description": "The variant is not approved yet, or the sample expired",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "429": {
      "description": "Too many voice requests; retry later",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "502": {
      "description": "Masko could not write the ideas or the adjustment; retry",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "503": {
      "description": "The voice service is unavailable; retry later",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  },
  "deprecated": true,
  "operationId": "legacyUpdateCollectionVoice"
}

DELETE/v1/collections/{id}/voiceRemove the voice

Removes the mascot's voice. Talking animations already made keep their sound; new ones need a voice.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

Responses

204 Removed

400 Invalid request

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Authentication required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 The key lacks permission, or the voice belongs to the Marketplace creator

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Mascot, variant or sample not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 The variant is not approved yet, or the sample expired

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

429 Too many voice requests; retry later

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

502 Masko could not write the ideas or the adjustment; retry

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

503 The voice service is unavailable; retry later

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Voice"
  ],
  "summary": "Remove the voice",
  "description": "Removes the mascot's voice. Talking animations already made keep their sound; new ones need a voice.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    }
  ],
  "responses": {
    "204": {
      "description": "Removed",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "400": {
      "description": "Invalid request",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "401": {
      "description": "Authentication required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "403": {
      "description": "The key lacks permission, or the voice belongs to the Marketplace creator",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "404": {
      "description": "Mascot, variant or sample not found",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "409": {
      "description": "The variant is not approved yet, or the sample expired",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "429": {
      "description": "Too many voice requests; retry later",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "502": {
      "description": "Masko could not write the ideas or the adjustment; retry",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "503": {
      "description": "The voice service is unavailable; retry later",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  },
  "deprecated": true,
  "operationId": "legacyDeleteCollectionVoice"
}

GET/v1/collections/{id}/voice/suggestionsSuggest voices

Returns voice ideas written for the mascot from its references and description. Each description is ready for POST /v1/collections/{id}/voice/samples. No credit cost.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

refreshquery

Return other ideas than a plain request would.

string · true, false

avoidquery

Comma-separated idea titles not to suggest again.

string

Responses

200 Voice ideas

application/json

dataobject · required

Nested fields

ideasarray · required

Nested fields

titlestring · required

A few words, such as "Cozy and warm".

descriptionstring · required

The full description, ready for POST .../voice/samples.

400 Invalid request

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Authentication required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 The key lacks permission, or the voice belongs to the Marketplace creator

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Mascot, variant or sample not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 The variant is not approved yet, or the sample expired

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

429 Too many voice requests; retry later

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

502 Masko could not write the ideas or the adjustment; retry

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

503 The voice service is unavailable; retry later

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Voice"
  ],
  "summary": "Suggest voices",
  "description": "Returns voice ideas written for the mascot from its references and description. Each description is ready for POST /v1/collections/{id}/voice/samples. No credit cost.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "schema": {
        "type": "string",
        "enum": [
          "true",
          "false"
        ],
        "description": "Return other ideas than a plain request would."
      },
      "required": false,
      "description": "Return other ideas than a plain request would.",
      "name": "refresh",
      "in": "query"
    },
    {
      "schema": {
        "type": "string",
        "maxLength": 500,
        "description": "Comma-separated idea titles not to suggest again."
      },
      "required": false,
      "description": "Comma-separated idea titles not to suggest again.",
      "name": "avoid",
      "in": "query"
    }
  ],
  "responses": {
    "200": {
      "description": "Voice ideas",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "ideas": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/VoiceIdea"
                    }
                  }
                },
                "required": [
                  "ideas"
                ]
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "400": {
      "description": "Invalid request",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "401": {
      "description": "Authentication required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "403": {
      "description": "The key lacks permission, or the voice belongs to the Marketplace creator",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "404": {
      "description": "Mascot, variant or sample not found",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "409": {
      "description": "The variant is not approved yet, or the sample expired",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "429": {
      "description": "Too many voice requests; retry later",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "502": {
      "description": "Masko could not write the ideas or the adjustment; retry",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "503": {
      "description": "The voice service is unavailable; retry later",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  },
  "deprecated": true,
  "operationId": "legacyListCollectionVoiceSuggestions"
}

POST/v1/collections/{id}/voice/adjustAdjust a voice description

Rewrites a voice description in one direction, such as "Older" or "Slower", and returns what changed plus directions that fit the new text. Without direction, returns only directions. No credit cost.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

Idempotency-Keyheader

string

Request body (required)

application/json

descriptionstring · required

The current voice description.

Length: 1 to 1000 characters

directionstring

A direction such as "Older" or "A little grumpy". Omit it to only get directions for this description.

Length: 0 to 80 characters

Responses

200 The rewritten description

application/json

dataobject · required

Nested fields

descriptionstring · required

The rewritten description.

changesarray · required

Each replaced or added passage. from is empty for added text.

Nested fields

fromstring · required

tostring · required

directionsarray · required

Directions that fit the new description.

Nested fields

string

400 Invalid request

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Authentication required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 The key lacks permission, or the voice belongs to the Marketplace creator

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Mascot, variant or sample not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 The variant is not approved yet, or the sample expired

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

429 Too many voice requests; retry later

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

502 Masko could not write the ideas or the adjustment; retry

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

503 The voice service is unavailable; retry later

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Voice"
  ],
  "summary": "Adjust a voice description",
  "description": "Rewrites a voice description in one direction, such as \"Older\" or \"Slower\", and returns what changed plus directions that fit the new text. Without direction, returns only directions. No credit cost.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.",
      "schema": {
        "type": "string",
        "maxLength": 255
      }
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/AdjustVoiceBody"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "The rewritten description",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/VoiceAdjustment"
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "400": {
      "description": "Invalid request",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "401": {
      "description": "Authentication required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "403": {
      "description": "The key lacks permission, or the voice belongs to the Marketplace creator",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "404": {
      "description": "Mascot, variant or sample not found",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "409": {
      "description": "The variant is not approved yet, or the sample expired",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "429": {
      "description": "Too many voice requests; retry later",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "502": {
      "description": "Masko could not write the ideas or the adjustment; retry",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "503": {
      "description": "The voice service is unavailable; retry later",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  },
  "deprecated": true,
  "operationId": "legacyAdjustCollectionVoice"
}

POST/v1/collections/{id}/voice/samplesHear voice samples

Designs three voices from a description, each reading the same line. Costs 1 credit for the three. Keep one with PUT /v1/collections/{id}/voice within 24 hours.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

Idempotency-Keyheader

string

Request body (required)

application/json

descriptionstring · required

How the voice sounds: age, pitch, pace, energy, texture, mood and accent.

Length: 20 to 1000 characters

sample_linestring

The line the samples read. Lines shorter than 100 characters are extended. Omit it for a line in the mascot's name.

Length: 0 to 500 characters

Responses

201 Three samples

application/json

dataobject · required

Nested fields

samplesarray · required

Nested fields

idstring · uuid · required

Pass it to PUT .../voice to keep this voice.

urlstring · uri · required

durationnumber · nullable · required

sample_linestring · required

cost_creditsnumber · required

expires_atstring · required

Samples not kept by then can no longer be kept.

400 Invalid request

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Authentication required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

402 Not enough credits

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 The key lacks permission, or the voice belongs to the Marketplace creator

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Mascot, variant or sample not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 The variant is not approved yet, or the sample expired

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

429 Too many voice requests; retry later

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

502 Masko could not write the ideas or the adjustment; retry

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

503 The voice service is unavailable; retry later

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Voice"
  ],
  "summary": "Hear voice samples",
  "description": "Designs three voices from a description, each reading the same line. Costs 1 credit for the three. Keep one with PUT /v1/collections/{id}/voice within 24 hours.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.",
      "schema": {
        "type": "string",
        "maxLength": 255
      }
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/VoiceSamplesBody"
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Three samples",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/VoiceSamples"
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "400": {
      "description": "Invalid request",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "401": {
      "description": "Authentication required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "402": {
      "description": "Not enough credits",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "403": {
      "description": "The key lacks permission, or the voice belongs to the Marketplace creator",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "404": {
      "description": "Mascot, variant or sample not found",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "409": {
      "description": "The variant is not approved yet, or the sample expired",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "429": {
      "description": "Too many voice requests; retry later",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "502": {
      "description": "Masko could not write the ideas or the adjustment; retry",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "503": {
      "description": "The voice service is unavailable; retry later",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  },
  "deprecated": true,
  "operationId": "legacyCreateCollectionVoiceSample"
}

GET/v1/collections/{id}/variants/{variantId}/voiceGet the voice of a variant

Returns the voice this variant speaks with: its own (source variant), the Original's until it gets one (source original), or null. sample_url is a short recording.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

variantIdpath · required

string

Responses

200 The voice, or null

application/json

dataobject · nullable · required

Nested fields

objectstring · required

Values: "voice"

namestring · required

descriptionstring · required

The words the voice was designed from.

sample_urlstring · uri · nullable · required

A short recording of the voice. Signed; fetch the voice again for a fresh link.

sourcestring · required

Whose voice this is: the mascot's own (original), the variant's own (variant), or the marketplace creator's (creator).

Values: "original", "variant", "creator"

created_atstring · required

400 Invalid request

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Authentication required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 The key lacks permission, or the voice belongs to the Marketplace creator

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Mascot, variant or sample not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 The variant is not approved yet, or the sample expired

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

429 Too many voice requests; retry later

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

502 Masko could not write the ideas or the adjustment; retry

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

503 The voice service is unavailable; retry later

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Voice"
  ],
  "summary": "Get the voice of a variant",
  "description": "Returns the voice this variant speaks with: its own (source variant), the Original's until it gets one (source original), or null. sample_url is a short recording.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "variantId",
      "in": "path"
    }
  ],
  "responses": {
    "200": {
      "description": "The voice, or null",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/Voice"
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "400": {
      "description": "Invalid request",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "401": {
      "description": "Authentication required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "403": {
      "description": "The key lacks permission, or the voice belongs to the Marketplace creator",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "404": {
      "description": "Mascot, variant or sample not found",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "409": {
      "description": "The variant is not approved yet, or the sample expired",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "429": {
      "description": "Too many voice requests; retry later",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "502": {
      "description": "Masko could not write the ideas or the adjustment; retry",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "503": {
      "description": "The voice service is unavailable; retry later",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  },
  "deprecated": true,
  "operationId": "legacyGetCollectionVariantVoice"
}

PUT/v1/collections/{id}/variants/{variantId}/voiceKeep a voice of a variant

Keeps one sample from POST /v1/collections/{id}/variants/{variantId}/voice/samples as the voice of an approved variant. It replaces the voice it had. Samples can be kept for 24 hours. No credit cost.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

variantIdpath · required

string

Request body (required)

application/json

sample_idstring · uuid · required

A sample from POST .../voice/samples.

namestring

Defaults to "<name>'s voice".

Length: 1 to 80 characters

Responses

200 The kept voice

application/json

dataobject · nullable · required

Nested fields

objectstring · required

Values: "voice"

namestring · required

descriptionstring · required

The words the voice was designed from.

sample_urlstring · uri · nullable · required

A short recording of the voice. Signed; fetch the voice again for a fresh link.

sourcestring · required

Whose voice this is: the mascot's own (original), the variant's own (variant), or the marketplace creator's (creator).

Values: "original", "variant", "creator"

created_atstring · required

400 Invalid request

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Authentication required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 The key lacks permission, or the voice belongs to the Marketplace creator

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Mascot, variant or sample not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 The variant is not approved yet, or the sample expired

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

429 Too many voice requests; retry later

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

502 Masko could not write the ideas or the adjustment; retry

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

503 The voice service is unavailable; retry later

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Voice"
  ],
  "summary": "Keep a voice of a variant",
  "description": "Keeps one sample from POST /v1/collections/{id}/variants/{variantId}/voice/samples as the voice of an approved variant. It replaces the voice it had. Samples can be kept for 24 hours. No credit cost.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "variantId",
      "in": "path"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/KeepVoiceBody"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "The kept voice",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/Voice"
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "400": {
      "description": "Invalid request",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "401": {
      "description": "Authentication required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "403": {
      "description": "The key lacks permission, or the voice belongs to the Marketplace creator",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "404": {
      "description": "Mascot, variant or sample not found",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "409": {
      "description": "The variant is not approved yet, or the sample expired",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "429": {
      "description": "Too many voice requests; retry later",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "502": {
      "description": "Masko could not write the ideas or the adjustment; retry",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "503": {
      "description": "The voice service is unavailable; retry later",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  },
  "deprecated": true,
  "operationId": "legacyUpdateCollectionVariantVoice"
}

DELETE/v1/collections/{id}/variants/{variantId}/voiceRemove the voice of a variant

Removes the variant's own voice; it speaks with the Original's voice again.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

variantIdpath · required

string

Responses

204 Removed

400 Invalid request

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Authentication required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 The key lacks permission, or the voice belongs to the Marketplace creator

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Mascot, variant or sample not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 The variant is not approved yet, or the sample expired

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

429 Too many voice requests; retry later

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

502 Masko could not write the ideas or the adjustment; retry

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

503 The voice service is unavailable; retry later

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Voice"
  ],
  "summary": "Remove the voice of a variant",
  "description": "Removes the variant's own voice; it speaks with the Original's voice again.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "variantId",
      "in": "path"
    }
  ],
  "responses": {
    "204": {
      "description": "Removed",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "400": {
      "description": "Invalid request",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "401": {
      "description": "Authentication required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "403": {
      "description": "The key lacks permission, or the voice belongs to the Marketplace creator",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "404": {
      "description": "Mascot, variant or sample not found",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "409": {
      "description": "The variant is not approved yet, or the sample expired",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "429": {
      "description": "Too many voice requests; retry later",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "502": {
      "description": "Masko could not write the ideas or the adjustment; retry",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "503": {
      "description": "The voice service is unavailable; retry later",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  },
  "deprecated": true,
  "operationId": "legacyDeleteCollectionVariantVoice"
}

GET/v1/collections/{id}/variants/{variantId}/voice/suggestionsSuggest voices of a variant

Returns voice ideas written for an approved variant from its references and description. Each description is ready for POST /v1/collections/{id}/variants/{variantId}/voice/samples. No credit cost.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

variantIdpath · required

string

refreshquery

Return other ideas than a plain request would.

string · true, false

avoidquery

Comma-separated idea titles not to suggest again.

string

Responses

200 Voice ideas

application/json

dataobject · required

Nested fields

ideasarray · required

Nested fields

titlestring · required

A few words, such as "Cozy and warm".

descriptionstring · required

The full description, ready for POST .../voice/samples.

400 Invalid request

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Authentication required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 The key lacks permission, or the voice belongs to the Marketplace creator

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Mascot, variant or sample not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 The variant is not approved yet, or the sample expired

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

429 Too many voice requests; retry later

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

502 Masko could not write the ideas or the adjustment; retry

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

503 The voice service is unavailable; retry later

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Voice"
  ],
  "summary": "Suggest voices of a variant",
  "description": "Returns voice ideas written for an approved variant from its references and description. Each description is ready for POST /v1/collections/{id}/variants/{variantId}/voice/samples. No credit cost.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "variantId",
      "in": "path"
    },
    {
      "schema": {
        "type": "string",
        "enum": [
          "true",
          "false"
        ],
        "description": "Return other ideas than a plain request would."
      },
      "required": false,
      "description": "Return other ideas than a plain request would.",
      "name": "refresh",
      "in": "query"
    },
    {
      "schema": {
        "type": "string",
        "maxLength": 500,
        "description": "Comma-separated idea titles not to suggest again."
      },
      "required": false,
      "description": "Comma-separated idea titles not to suggest again.",
      "name": "avoid",
      "in": "query"
    }
  ],
  "responses": {
    "200": {
      "description": "Voice ideas",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "ideas": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/VoiceIdea"
                    }
                  }
                },
                "required": [
                  "ideas"
                ]
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "400": {
      "description": "Invalid request",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "401": {
      "description": "Authentication required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "403": {
      "description": "The key lacks permission, or the voice belongs to the Marketplace creator",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "404": {
      "description": "Mascot, variant or sample not found",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "409": {
      "description": "The variant is not approved yet, or the sample expired",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "429": {
      "description": "Too many voice requests; retry later",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "502": {
      "description": "Masko could not write the ideas or the adjustment; retry",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "503": {
      "description": "The voice service is unavailable; retry later",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  },
  "deprecated": true,
  "operationId": "legacyListCollectionVariantVoiceSuggestions"
}

POST/v1/collections/{id}/variants/{variantId}/voice/adjustAdjust a voice description of a variant

Rewrites a voice description in one direction, such as "Older" or "Slower", and returns what changed plus directions that fit the new text. Without direction, returns only directions. No credit cost.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

variantIdpath · required

string

Idempotency-Keyheader

string

Request body (required)

application/json

descriptionstring · required

The current voice description.

Length: 1 to 1000 characters

directionstring

A direction such as "Older" or "A little grumpy". Omit it to only get directions for this description.

Length: 0 to 80 characters

Responses

200 The rewritten description

application/json

dataobject · required

Nested fields

descriptionstring · required

The rewritten description.

changesarray · required

Each replaced or added passage. from is empty for added text.

Nested fields

fromstring · required

tostring · required

directionsarray · required

Directions that fit the new description.

Nested fields

string

400 Invalid request

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Authentication required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 The key lacks permission, or the voice belongs to the Marketplace creator

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Mascot, variant or sample not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 The variant is not approved yet, or the sample expired

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

429 Too many voice requests; retry later

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

502 Masko could not write the ideas or the adjustment; retry

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

503 The voice service is unavailable; retry later

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Voice"
  ],
  "summary": "Adjust a voice description of a variant",
  "description": "Rewrites a voice description in one direction, such as \"Older\" or \"Slower\", and returns what changed plus directions that fit the new text. Without direction, returns only directions. No credit cost.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "variantId",
      "in": "path"
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.",
      "schema": {
        "type": "string",
        "maxLength": 255
      }
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/AdjustVoiceBody"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "The rewritten description",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/VoiceAdjustment"
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "400": {
      "description": "Invalid request",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "401": {
      "description": "Authentication required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "403": {
      "description": "The key lacks permission, or the voice belongs to the Marketplace creator",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "404": {
      "description": "Mascot, variant or sample not found",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "409": {
      "description": "The variant is not approved yet, or the sample expired",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "429": {
      "description": "Too many voice requests; retry later",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "502": {
      "description": "Masko could not write the ideas or the adjustment; retry",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "503": {
      "description": "The voice service is unavailable; retry later",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  },
  "deprecated": true,
  "operationId": "legacyAdjustCollectionVariantVoice"
}

POST/v1/collections/{id}/variants/{variantId}/voice/samplesHear voice samples of a variant

Designs three voices from a description, each reading the same line. Costs 1 credit for the three. Keep one with PUT /v1/collections/{id}/variants/{variantId}/voice within 24 hours.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

variantIdpath · required

string

Idempotency-Keyheader

string

Request body (required)

application/json

descriptionstring · required

How the voice sounds: age, pitch, pace, energy, texture, mood and accent.

Length: 20 to 1000 characters

sample_linestring

The line the samples read. Lines shorter than 100 characters are extended. Omit it for a line in the mascot's name.

Length: 0 to 500 characters

Responses

201 Three samples

application/json

dataobject · required

Nested fields

samplesarray · required

Nested fields

idstring · uuid · required

Pass it to PUT .../voice to keep this voice.

urlstring · uri · required

durationnumber · nullable · required

sample_linestring · required

cost_creditsnumber · required

expires_atstring · required

Samples not kept by then can no longer be kept.

400 Invalid request

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Authentication required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

402 Not enough credits

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 The key lacks permission, or the voice belongs to the Marketplace creator

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Mascot, variant or sample not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 The variant is not approved yet, or the sample expired

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

429 Too many voice requests; retry later

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

502 Masko could not write the ideas or the adjustment; retry

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

503 The voice service is unavailable; retry later

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Voice"
  ],
  "summary": "Hear voice samples of a variant",
  "description": "Designs three voices from a description, each reading the same line. Costs 1 credit for the three. Keep one with PUT /v1/collections/{id}/variants/{variantId}/voice within 24 hours.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "variantId",
      "in": "path"
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.",
      "schema": {
        "type": "string",
        "maxLength": 255
      }
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/VoiceSamplesBody"
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Three samples",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/VoiceSamples"
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "400": {
      "description": "Invalid request",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "401": {
      "description": "Authentication required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "402": {
      "description": "Not enough credits",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "403": {
      "description": "The key lacks permission, or the voice belongs to the Marketplace creator",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "404": {
      "description": "Mascot, variant or sample not found",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "409": {
      "description": "The variant is not approved yet, or the sample expired",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "429": {
      "description": "Too many voice requests; retry later",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "502": {
      "description": "Masko could not write the ideas or the adjustment; retry",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "503": {
      "description": "The voice service is unavailable; retry later",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  },
  "deprecated": true,
  "operationId": "legacyCreateCollectionVariantVoiceSample"
}

GET/v1/projectsList projects

Returns all projects owned by the authenticated user, paginated. Projects are the top-level containers for mascots. No credit cost.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

limitquery

Page size. 1 to 100. Defaults to 50.

number

offsetquery

Number of records to skip. Defaults to 0.

number

cursorquery

Opaque next_cursor from the previous page. Use instead of offset.

string

Masko-API-Versionheader

Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract.

string · 2026-09-26, legacy

api_versionquery

Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree.

string · 2026-09-26, legacy

Responses

200 List of projects

application/json

dataarray · required

Nested fields

objectstring

Resource type. Always "project".

Values: "project"

idstring · uuid · required

namestring · required

organization_idstring · uuid · nullable · required

created_atstring · required

updated_atstring · required

metaobject · required

Nested fields

paginationobject

Nested fields

totalinteger · required

Range: 0 to unbounded

limitinteger · required

Range: 0 to unbounded

offsetinteger · required

Range: 0 to unbounded

has_moreboolean · required

next_cursorstring · nullable

Pass as the cursor query parameter to get the next page. Null on the last page.

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Projects"
  ],
  "summary": "List projects",
  "description": "Returns all projects owned by the authenticated user, paginated. Projects are the top-level containers for mascots. No credit cost.\n\nSelect Masko-API-Version: 2026-09-26 (or api_version=2026-09-26) for the canonical mascot contract shown first. Existing unversioned clients keep legacy collection fields. A mascot_id query filter also selects the canonical contract. Mixing identifier names returns 400.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "number",
        "minimum": 1,
        "maximum": 100,
        "default": 50,
        "description": "Page size. 1 to 100. Defaults to 50."
      },
      "required": false,
      "description": "Page size. 1 to 100. Defaults to 50.",
      "name": "limit",
      "in": "query"
    },
    {
      "schema": {
        "type": "number",
        "nullable": true,
        "minimum": 0,
        "default": 0,
        "description": "Number of records to skip. Defaults to 0."
      },
      "required": false,
      "description": "Number of records to skip. Defaults to 0.",
      "name": "offset",
      "in": "query"
    },
    {
      "schema": {
        "type": "string",
        "description": "Opaque next_cursor from the previous page. Use instead of offset."
      },
      "required": false,
      "description": "Opaque next_cursor from the previous page. Use instead of offset.",
      "name": "cursor",
      "in": "query"
    },
    {
      "in": "header",
      "name": "Masko-API-Version",
      "required": false,
      "schema": {
        "type": "string",
        "enum": [
          "2026-09-26",
          "legacy"
        ]
      },
      "description": "Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract."
    },
    {
      "in": "query",
      "name": "api_version",
      "required": false,
      "schema": {
        "type": "string",
        "enum": [
          "2026-09-26",
          "legacy"
        ]
      },
      "description": "Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree."
    }
  ],
  "responses": {
    "200": {
      "description": "List of projects",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ProjectListResponse"
          },
          "example": {
            "data": [
              {
                "id": "04dae799-dd9a-4296-ba86-9e3913c2f8d1",
                "name": "test",
                "created_at": "2026-04-08T03:30:21.168491+00:00",
                "updated_at": "2026-04-08T03:30:21.168491+00:00",
                "organization_id": "bc5a4520-ee23-46e7-b714-2835bd3a7f80"
              }
            ],
            "meta": {
              "pagination": {
                "total": 2,
                "limit": 5,
                "offset": 0,
                "has_more": false
              }
            }
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    }
  },
  "operationId": "listProjects"
}

POST/v1/projectsCreate a project

Creates a new project under the authenticated user. Projects are lightweight containers - create one per product or per workspace. Returns 201 with the new project record. No credit cost.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

Idempotency-Keyheader

string

Masko-API-Versionheader

Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract.

string · 2026-09-26, legacy

api_versionquery

Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree.

string · 2026-09-26, legacy

Request body (required)

Request body

application/json

namestring · required

Project display name. 1 to 255 characters.

Length: 1 to 255 characters

Responses

201 Created project

application/json

dataobject · required

Nested fields

objectstring

Resource type. Always "project".

Values: "project"

idstring · uuid · required

namestring · required

organization_idstring · uuid · nullable · required

created_atstring · required

updated_atstring · required

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Projects"
  ],
  "summary": "Create a project",
  "description": "Creates a new project under the authenticated user. Projects are lightweight containers - create one per product or per workspace. Returns 201 with the new project record. No credit cost.\n\nSelect Masko-API-Version: 2026-09-26 (or api_version=2026-09-26) for the canonical mascot contract shown first. Existing unversioned clients keep legacy collection fields. A mascot_id query filter also selects the canonical contract. Mixing identifier names returns 400.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "requestBody": {
    "required": true,
    "description": "Request body",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/CreateProjectBody"
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Created project",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ProjectResponse"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    }
  },
  "operationId": "createProject",
  "parameters": [
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.",
      "schema": {
        "type": "string",
        "maxLength": 255
      }
    },
    {
      "in": "header",
      "name": "Masko-API-Version",
      "required": false,
      "schema": {
        "type": "string",
        "enum": [
          "2026-09-26",
          "legacy"
        ]
      },
      "description": "Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract."
    },
    {
      "in": "query",
      "name": "api_version",
      "required": false,
      "schema": {
        "type": "string",
        "enum": [
          "2026-09-26",
          "legacy"
        ]
      },
      "description": "Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree."
    }
  ]
}

GET/v1/collectionsList collections

Returns all collections owned by the authenticated user, paginated. A collection is a single mascot character with its own style, references, and items. No credit cost.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

limitquery

Page size. 1 to 100. Defaults to 50.

number

offsetquery

Number of records to skip. Defaults to 0.

number

cursorquery

Opaque next_cursor from the previous page. Use instead of offset.

string

project_idquery

Filter to this project.

string

typequery

Filter by type, e.g. "mascot".

string

Responses

200 List of collections

application/json

dataarray · required

Nested fields

objectstring

Resource type. Always "mascot".

Values: "mascot"

idstring · uuid · required

namestring · required

typestring · required

project_idstring · uuid

configobject

Nested fields

promptstring · required

reference_asset_idsarray · required

Nested fields

string

style_cardobject · nullable · required

caution_listarray · required

Nested fields

string

is_publishedboolean

slugstring · nullable

user_prefixstring · nullable

room_for_movementboolean

Room for movement. When true, new animations are made from the mascot's poses shrunk to 80% of their picture, so jumps, wings and raised arms stay inside the video; the mascot looks 20% smaller in each file. New mascots start with true; mascots made before the setting existed start with false. A canvas keeps the size of the clips already on it, and an edit keeps its source clip's size.

cdn_statusarray

Nested fields

asset_idstring · uuid · required

item_namestring · nullable · required

typestring · required

cdn_urlstring · uri · required

statusstring · required

file_sizenumber · nullable · required

created_atstring · required

updated_atstring · required

metaobject · required

Nested fields

paginationobject

Nested fields

totalinteger · required

Range: 0 to unbounded

limitinteger · required

Range: 0 to unbounded

offsetinteger · required

Range: 0 to unbounded

has_moreboolean · required

next_cursorstring · nullable

Pass as the cursor query parameter to get the next page. Null on the last page.

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Collections"
  ],
  "summary": "List collections",
  "description": "Returns all collections owned by the authenticated user, paginated. A collection is a single mascot character with its own style, references, and items. No credit cost.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "number",
        "minimum": 1,
        "maximum": 100,
        "default": 50,
        "description": "Page size. 1 to 100. Defaults to 50."
      },
      "required": false,
      "description": "Page size. 1 to 100. Defaults to 50.",
      "name": "limit",
      "in": "query"
    },
    {
      "schema": {
        "type": "number",
        "nullable": true,
        "minimum": 0,
        "default": 0,
        "description": "Number of records to skip. Defaults to 0."
      },
      "required": false,
      "description": "Number of records to skip. Defaults to 0.",
      "name": "offset",
      "in": "query"
    },
    {
      "schema": {
        "type": "string",
        "description": "Opaque next_cursor from the previous page. Use instead of offset."
      },
      "required": false,
      "description": "Opaque next_cursor from the previous page. Use instead of offset.",
      "name": "cursor",
      "in": "query"
    },
    {
      "schema": {
        "type": "string",
        "format": "uuid",
        "description": "Filter to this project."
      },
      "required": false,
      "description": "Filter to this project.",
      "name": "project_id",
      "in": "query"
    },
    {
      "schema": {
        "type": "string",
        "description": "Filter by type, e.g. \"mascot\"."
      },
      "required": false,
      "description": "Filter by type, e.g. \"mascot\".",
      "name": "type",
      "in": "query"
    }
  ],
  "responses": {
    "200": {
      "description": "List of collections",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CollectionListResponse"
          },
          "example": {
            "data": [
              {
                "id": "f9503022-a991-46ea-bf8c-d628c921b6b0",
                "name": "v1-api-test-cat-1776591403",
                "type": "mascot",
                "project_id": "04dae799-dd9a-4296-ba86-9e3913c2f8d1",
                "project_name": "test",
                "is_published": true,
                "public_slug": "v1-api-test-cat-1776591403-rmau1uyd",
                "user_prefix": "fda8417d",
                "created_at": "2026-04-19T09:36:43.46139+00:00"
              }
            ],
            "meta": {
              "pagination": {
                "total": 6,
                "limit": 5,
                "offset": 0,
                "has_more": true
              }
            }
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    }
  },
  "deprecated": true,
  "operationId": "legacyListCollections"
}

POST/v1/collectionsCreate a mascot (collection)

This is the primary way to create a mascot. In the API the resource is called collection - today one collection holds one mascot so the terms are interchangeable. Recommended input is reference images (reference_image_urls or reference_asset_ids from POST /v1/upload) - one or more images of the character. The references ARE the mascot; you do not need to describe it in prompt. Use context to add things the image cannot express: personality, consistency rules ("always wears red sneakers"), forbidden variants ("never without the hat"), brand tone. The collection is assigned to a project and gets a public CDN slug. Creation with existing references or name/context only is free. Providing prompt without references generates one reference for 1 credit. Failed generation, storage or persistence triggers a refund, with background retries if immediate repayment fails. Use Idempotency-Key to replay a request without generating or charging again. Future /generate calls use the style automatically extracted from the references.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

Idempotency-Keyheader

string

Request body (required)

Request body

application/json

project_idstring · uuid · required

Project to create the collection in. List projects via GET /v1/projects.

namestring

Display name. Defaults to a generated name if omitted.

promptstring

Optional - do not set this if your references already show the mascot clearly. The reference images ARE the character. Only use prompt when you cannot provide references (pure text-to-mascot). When references are present, a prompt is auto-extracted from them. Without references, prompt generates one reference for 1 credit; a failed creation is refunded.

contextstring

Extra hints the image alone cannot convey: personality and behavior ("curious, cautious, never aggressive"), consistency rules ("always has a small white star on left ear"), forbidden variants ("never show without the hat"), brand tone. Not a character description - the references cover that.

typestring

Collection type. Defaults to "mascot".

Default: "mascot"

stylestring

Style ID or name. List styles via GET /v1/styles.

design_touchesarray

Optional design ideas for text-to-mascot creation, the same touches as the Studio creator. Requires prompt and no references. Each touch is added to the generated reference and applied only where it fits the character; the prompt wins where they differ. Pick at most one eyes-* and one mood-* value. Shape: proportions, simple, asymmetry, grounded, few-colors. Face: no-mouth, looks-at-you, blush, eyes-big, eyes-dots. Character: signature, weird, twist, grown-up-flaw, magic-part, mood-cozy, mood-mischievous, mood-melancholy, mood-bold, mood-mysterious, mood-chaotic, mood-serene.

Items: 0 to 22

Nested fields

string · proportions, simple, asymmetry, grounded, few-colors, no-mouth, looks-at-you, blush, eyes-big, eyes-dots, signature, weird, twist, grown-up-flaw, magic-part, mood-cozy, mood-mischievous, mood-melancholy, mood-bold, mood-mysterious, mood-chaotic, mood-serene

reference_image_urlsarray

Recommended entry point. Public image URLs of the mascot - at least one, up to 6. Each public HTTP(S) URL is downloaded with a 10 MB limit and a 15-second deadline; private addresses and unsafe redirects are rejected. PNG, JPEG, WebP, GIF and SVG are supported; SVG is converted to PNG. Each is stored as an asset. The first reference acts as the canonical look; additional ones widen angle/pose coverage. If you also pass reference_asset_ids, totals combine up to 6.

Nested fields

string

reference_asset_idsarray

Existing asset IDs to use as references. A fresh upload from POST /v1/upload joins this mascot. An image that already belongs to another mascot stays there, and this mascot gets its own reference copy of it. Max 6 references combined with reference_image_urls.

Nested fields

string

settingsobject

Collection settings. cdn_enabled: whether new assets auto-publish to the CDN. animation_sizes: up to 2 smaller pixel widths to auto-generate variants for, e.g. [480, 240]. Every animation already gets its 720 px files, so 720 and larger values are ignored. Common values: 480, 360, 240, 128.

Nested fields

cdn_enabledboolean

Default: true

animation_sizesarray

Nested fields

number

Responses

201 Created collection

application/json

dataobject · required

Nested fields

objectstring

Resource type. Always "mascot".

Values: "mascot"

idstring · uuid · required

namestring · required

typestring · required

project_idstring · uuid

configobject

Nested fields

promptstring · required

reference_asset_idsarray · required

Nested fields

string

style_cardobject · nullable · required

caution_listarray · required

Nested fields

string

is_publishedboolean

slugstring · nullable

user_prefixstring · nullable

room_for_movementboolean

cdn_statusarray

Nested fields

asset_idstring · uuid · required

item_namestring · nullable · required

typestring · required

cdn_urlstring · uri · required

statusstring · required

file_sizenumber · nullable · required

created_atstring · required

updated_atstring · required

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Collections"
  ],
  "summary": "Create a mascot (collection)",
  "description": "This is the primary way to create a mascot. In the API the resource is called `collection` - today one collection holds one mascot so the terms are interchangeable. Recommended input is reference images (`reference_image_urls` or `reference_asset_ids` from POST /v1/upload) - one or more images of the character. The references ARE the mascot; you do not need to describe it in `prompt`. Use `context` to add things the image cannot express: personality, consistency rules (\"always wears red sneakers\"), forbidden variants (\"never without the hat\"), brand tone. The collection is assigned to a project and gets a public CDN slug. Creation with existing references or name/context only is free. Providing prompt without references generates one reference for 1 credit. Failed generation, storage or persistence triggers a refund, with background retries if immediate repayment fails. Use Idempotency-Key to replay a request without generating or charging again. Future /generate calls use the style automatically extracted from the references.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "requestBody": {
    "required": true,
    "description": "Request body",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/CreateCollectionBody"
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Created collection",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CollectionResponse"
          },
          "example": {
            "data": {
              "id": "f9503022-a991-46ea-bf8c-d628c921b6b0",
              "name": "v1-api-test-cat-1776591403",
              "slug": "v1-api-test-cat-1776591403-rmau1uyd",
              "type": "mascot",
              "reference_asset_ids": [
                "e906ebb5-deb1-4010-82f9-f0182a3812e0",
                "5114bec3-b92a-4917-8675-84fce713d3cf"
              ],
              "settings": {
                "cdn_enabled": true,
                "animation_sizes": []
              }
            }
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    }
  },
  "deprecated": true,
  "operationId": "legacyCreateCollection",
  "parameters": [
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.",
      "schema": {
        "type": "string",
        "maxLength": 255
      }
    }
  ]
}

GET/v1/collections/{id}Get collection details

Returns the full collection record including config (prompt, reference_asset_ids, style_card, caution_list) and cdn_status. Returns 404 if the collection does not exist or is not owned by the caller.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

Responses

200 Collection details with cdn_status

application/json

dataobject · required

Nested fields

objectstring

Resource type. Always "mascot".

Values: "mascot"

idstring · uuid · required

namestring · required

typestring · required

project_idstring · uuid

configobject

Nested fields

promptstring · required

reference_asset_idsarray · required

Nested fields

string

style_cardobject · nullable · required

caution_listarray · required

Nested fields

string

is_publishedboolean

slugstring · nullable

user_prefixstring · nullable

room_for_movementboolean

cdn_statusarray

Nested fields

asset_idstring · uuid · required

item_namestring · nullable · required

typestring · required

cdn_urlstring · uri · required

statusstring · required

file_sizenumber · nullable · required

created_atstring · required

updated_atstring · required

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Collections"
  ],
  "summary": "Get collection details",
  "description": "Returns the full collection record including config (prompt, reference_asset_ids, style_card, caution_list) and cdn_status. Returns 404 if the collection does not exist or is not owned by the caller.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    }
  ],
  "responses": {
    "200": {
      "description": "Collection details with cdn_status",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CollectionResponse"
          },
          "example": {
            "data": {
              "id": "f9503022-a991-46ea-bf8c-d628c921b6b0",
              "name": "v1-api-test-cat-1776591403",
              "type": "mascot",
              "project_id": "04dae799-dd9a-4296-ba86-9e3913c2f8d1",
              "config": {
                "prompt": "terracotta clay cat mascot with big eyes and speckled texture",
                "reference_asset_ids": [
                  "e906ebb5-deb1-4010-82f9-f0182a3812e0",
                  "5114bec3-b92a-4917-8675-84fce713d3cf"
                ],
                "style_card": null,
                "caution_list": []
              },
              "is_published": true,
              "slug": "v1-api-test-cat-1776591403-rmau1uyd",
              "user_prefix": "fda8417d",
              "cdn_status": [],
              "created_at": "2026-04-19T09:36:43.46139+00:00",
              "updated_at": "2026-04-19T09:36:46.966862+00:00"
            }
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    }
  },
  "deprecated": true,
  "operationId": "legacyGetCollection"
}

PATCH/v1/collections/{id}Update collection metadata

Updates a collection name, prompt, or public slug. Returns { updated: true }. Returns 404 if not found or not owned by the caller. No credit cost.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

Request body (required)

Request body

application/json

namestring

New display name.

contextstring

Updated brand or product context.

slugstring

CDN slug for this collection. Used in the public URL path: https://assets.masko.ai/:user_prefix/:slug/... Globally unique across all collections. Normalized server-side: lowercased, non-alphanumeric stripped (hyphens kept), trimmed. After normalization must be 2 to 50 characters. Returns 409 if taken.

Length: 2 to 50 characters

configobject

Raw config object merged into existing config. Advanced use only: prefer dedicated endpoints /references and /settings; set slug with PATCH /v1/collections/:id.

room_for_movementboolean

Responses

200 Updated collection

application/json

dataobject · required

Nested fields

updatedboolean · required

slugstring

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Collections"
  ],
  "summary": "Update collection metadata",
  "description": "Updates a collection name, prompt, or public slug. Returns { updated: true }. Returns 404 if not found or not owned by the caller. No credit cost.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    }
  ],
  "requestBody": {
    "required": true,
    "description": "Request body",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/UpdateCollectionBody"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Updated collection",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/UpdatedFlagResponse"
          },
          "example": {
            "data": {
              "updated": true
            }
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    }
  },
  "deprecated": true,
  "operationId": "legacyUpdateCollection"
}

GET/v1/collections/{id}/itemsList items in a collection

Returns paginated items in a collection. An item groups related assets (e.g. "wave" item may have an image, a transparent image, and animation variants). Filter by type to narrow results. No credit cost.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

limitquery

Page size. 1 to 100. Defaults to 50.

number

offsetquery

Number of records to skip. Defaults to 0.

number

cursorquery

Opaque next_cursor from the previous page. Use instead of offset.

string

typequery

string

Responses

200 List of items

application/json

dataarray · required

Nested fields

objectstring

Resource type. Always "item".

Values: "item"

idstring · uuid · required

namestring · required

typestring · required

promptstring · required

public_slugstring · nullable · required

metadataobject · nullable

created_atstring · required

metaobject · required

Nested fields

paginationobject

Nested fields

totalinteger · required

Range: 0 to unbounded

limitinteger · required

Range: 0 to unbounded

offsetinteger · required

Range: 0 to unbounded

has_moreboolean · required

next_cursorstring · nullable

Pass as the cursor query parameter to get the next page. Null on the last page.

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Items"
  ],
  "summary": "List items in a collection",
  "description": "Returns paginated items in a collection. An item groups related assets (e.g. \"wave\" item may have an image, a transparent image, and animation variants). Filter by `type` to narrow results. No credit cost.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "schema": {
        "type": "number",
        "minimum": 1,
        "maximum": 100,
        "default": 50,
        "description": "Page size. 1 to 100. Defaults to 50."
      },
      "required": false,
      "description": "Page size. 1 to 100. Defaults to 50.",
      "name": "limit",
      "in": "query"
    },
    {
      "schema": {
        "type": "number",
        "nullable": true,
        "minimum": 0,
        "default": 0,
        "description": "Number of records to skip. Defaults to 0."
      },
      "required": false,
      "description": "Number of records to skip. Defaults to 0.",
      "name": "offset",
      "in": "query"
    },
    {
      "schema": {
        "type": "string",
        "description": "Opaque next_cursor from the previous page. Use instead of offset."
      },
      "required": false,
      "description": "Opaque next_cursor from the previous page. Use instead of offset.",
      "name": "cursor",
      "in": "query"
    },
    {
      "schema": {
        "type": "string"
      },
      "required": false,
      "name": "type",
      "in": "query"
    }
  ],
  "responses": {
    "200": {
      "description": "List of items",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ItemListResponse"
          },
          "example": {
            "data": [],
            "meta": {
              "pagination": {
                "total": 0,
                "limit": 5,
                "offset": 0,
                "has_more": false
              }
            }
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    }
  },
  "deprecated": true,
  "operationId": "legacyListCollectionItems"
}

GET/v1/collections/{id}/items/{itemId}Get item details

Returns the item record with all its generated assets (images, animations, logos). Returns 404 if the item does not exist or is not in the given collection. No credit cost.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

itemIdpath · required

string

Responses

200 Item details with assets

application/json

dataobject · required

Nested fields

Item

objectstring

Resource type. Always "item".

Values: "item"

idstring · uuid · required

namestring · required

typestring · required

promptstring · required

public_slugstring · nullable · required

metadataobject · nullable

created_atstring · required

Option 2

assetsarray · required

Nested fields

objectstring

Resource type. Always "asset".

Values: "asset"

idstring · uuid · required

typestring · required

Values: "interactive", "interactive_frame", "image", "transparent_image", "sticker_image", "svg", "video", "webm", "hevc", "stacked_video", "stacked_video_av1", "logo", "audio", "transcript"

statusstring · required

metadataobject · nullable

Media dimensions, format and public asset context. Internal generation execution details are omitted.

item_idstring · uuid · nullable · required

collection_idstring · uuid · nullable

file_urlstring · uri · nullable · required

cdn_urlstring · uri · nullable · required

file_sizeinteger · nullable

Size of the file in bytes; null until the file is completed, or when it cannot be read.

is_archivedboolean

archived_atstring · nullable

created_atstring · required

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Items"
  ],
  "summary": "Get item details",
  "description": "Returns the item record with all its generated assets (images, animations, logos). Returns 404 if the item does not exist or is not in the given collection. No credit cost.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "itemId",
      "in": "path"
    }
  ],
  "responses": {
    "200": {
      "description": "Item details with assets",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ItemResponse"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    }
  },
  "deprecated": true,
  "operationId": "legacyGetCollectionItem"
}

PATCH/v1/collections/{id}/items/{itemId}Update item name or prompt

Updates the item name (used to derive the public slug) and/or the prompt. Does not re-generate assets. No credit cost.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

itemIdpath · required

string

Request body (required)

Request body

application/json

namestring

Length: 1 to unbounded characters

promptstring

Responses

200 Updated item

application/json

dataobject · required

Nested fields

Item

objectstring

Resource type. Always "item".

Values: "item"

idstring · uuid · required

namestring · required

typestring · required

promptstring · required

public_slugstring · nullable · required

metadataobject · nullable

created_atstring · required

Option 2

assetsarray · required

Nested fields

objectstring

Resource type. Always "asset".

Values: "asset"

idstring · uuid · required

typestring · required

Values: "interactive", "interactive_frame", "image", "transparent_image", "sticker_image", "svg", "video", "webm", "hevc", "stacked_video", "stacked_video_av1", "logo", "audio", "transcript"

statusstring · required

metadataobject · nullable

Media dimensions, format and public asset context. Internal generation execution details are omitted.

item_idstring · uuid · nullable · required

collection_idstring · uuid · nullable

file_urlstring · uri · nullable · required

cdn_urlstring · uri · nullable · required

file_sizeinteger · nullable

Size of the file in bytes; null until the file is completed, or when it cannot be read.

is_archivedboolean

archived_atstring · nullable

created_atstring · required

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Items"
  ],
  "summary": "Update item name or prompt",
  "description": "Updates the item name (used to derive the public slug) and/or the prompt. Does not re-generate assets. No credit cost.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "itemId",
      "in": "path"
    }
  ],
  "requestBody": {
    "required": true,
    "description": "Request body",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/UpdateItemBody"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Updated item",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ItemResponse"
          },
          "example": {
            "data": {
              "id": "e8ca0d1b-b445-46f6-862f-26b26ac2c6ff",
              "name": "sitting-calmly",
              "prompt": "sitting on ground with closed eyes peacefully",
              "public_slug": "sitting",
              "created_at": "2026-04-19T09:44:26.659167+00:00"
            }
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    }
  },
  "deprecated": true,
  "operationId": "legacyUpdateCollectionItem"
}

DELETE/v1/collections/{id}/items/{itemId}Archive an item

Soft-deletes (archives) the item and its assets. Files are retained but filtered from reads. Returns 204 on success. No credit cost.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

itemIdpath · required

string

Responses

204 Archived

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Items"
  ],
  "summary": "Archive an item",
  "description": "Soft-deletes (archives) the item and its assets. Files are retained but filtered from reads. Returns 204 on success. No credit cost.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "itemId",
      "in": "path"
    }
  ],
  "responses": {
    "204": {
      "description": "Archived",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    }
  },
  "deprecated": true,
  "operationId": "legacyDeleteCollectionItem"
}

GET/v1/collections/{id}/assetsList assets in a collection

Returns paginated assets in a collection (images, videos, transparent variants). Each asset has a signed file_url (1-hour expiry) and a cdn_url when published. Filter by type or item_id. Set include_file_urls=false for faster metadata-only listings. No credit cost.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

limitquery

Page size. 1 to 100. Defaults to 50.

number

offsetquery

Number of records to skip. Defaults to 0.

number

cursorquery

Opaque next_cursor from the previous page. Use instead of offset.

string

typequery

string

item_idquery

string

include_file_urlsquery

Whether to include signed file_url values. Defaults to true. Set false for faster metadata-only listings.

string · true, false

Responses

200 List of assets

application/json

dataarray · required

Nested fields

objectstring

Resource type. Always "asset".

Values: "asset"

idstring · uuid · required

typestring · required

Values: "interactive", "interactive_frame", "image", "transparent_image", "sticker_image", "svg", "video", "webm", "hevc", "stacked_video", "stacked_video_av1", "logo", "audio", "transcript"

statusstring · required

metadataobject · nullable

Media dimensions, format and public asset context. Internal generation execution details are omitted.

item_idstring · uuid · nullable · required

collection_idstring · uuid · nullable

file_urlstring · uri · nullable · required

cdn_urlstring · uri · nullable · required

file_sizeinteger · nullable

Size of the file in bytes; null until the file is completed, or when it cannot be read.

is_archivedboolean

archived_atstring · nullable

created_atstring · required

metaobject · required

Nested fields

paginationobject

Nested fields

totalinteger · required

Range: 0 to unbounded

limitinteger · required

Range: 0 to unbounded

offsetinteger · required

Range: 0 to unbounded

has_moreboolean · required

next_cursorstring · nullable

Pass as the cursor query parameter to get the next page. Null on the last page.

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Assets"
  ],
  "summary": "List assets in a collection",
  "description": "Returns paginated assets in a collection (images, videos, transparent variants). Each asset has a signed `file_url` (1-hour expiry) and a `cdn_url` when published. Filter by `type` or `item_id`. Set `include_file_urls=false` for faster metadata-only listings. No credit cost.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "schema": {
        "type": "number",
        "minimum": 1,
        "maximum": 100,
        "default": 50,
        "description": "Page size. 1 to 100. Defaults to 50."
      },
      "required": false,
      "description": "Page size. 1 to 100. Defaults to 50.",
      "name": "limit",
      "in": "query"
    },
    {
      "schema": {
        "type": "number",
        "nullable": true,
        "minimum": 0,
        "default": 0,
        "description": "Number of records to skip. Defaults to 0."
      },
      "required": false,
      "description": "Number of records to skip. Defaults to 0.",
      "name": "offset",
      "in": "query"
    },
    {
      "schema": {
        "type": "string",
        "description": "Opaque next_cursor from the previous page. Use instead of offset."
      },
      "required": false,
      "description": "Opaque next_cursor from the previous page. Use instead of offset.",
      "name": "cursor",
      "in": "query"
    },
    {
      "schema": {
        "type": "string"
      },
      "required": false,
      "name": "type",
      "in": "query"
    },
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": false,
      "name": "item_id",
      "in": "query"
    },
    {
      "schema": {
        "type": "string",
        "enum": [
          "true",
          "false"
        ],
        "description": "Whether to include signed file_url values. Defaults to true. Set false for faster metadata-only listings."
      },
      "required": false,
      "description": "Whether to include signed file_url values. Defaults to true. Set false for faster metadata-only listings.",
      "name": "include_file_urls",
      "in": "query"
    }
  ],
  "responses": {
    "200": {
      "description": "List of assets",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AssetListResponse"
          },
          "example": {
            "data": [
              {
                "id": "5114bec3-b92a-4917-8675-84fce713d3cf",
                "type": "image",
                "status": "completed",
                "metadata": {},
                "item_id": null,
                "file_url": "https://storage.googleapis.com/masco-media/references/.../f4bdfb19.png?GoogleAccessId=...&Expires=...&Signature=...",
                "cdn_url": null,
                "created_at": "2026-04-19T09:36:46.95543+00:00"
              }
            ],
            "meta": {
              "pagination": {
                "total": 2,
                "limit": 5,
                "offset": 0,
                "has_more": false
              }
            }
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    }
  },
  "deprecated": true,
  "operationId": "legacyListCollectionAssets"
}

GET/v1/collections/{id}/cdn-exportExport published CDN links

Returns the same clean hosted-link JSON shown in the collection page Get Links export modal. This endpoint is built from published CDN assets, not raw item types, so pose/image items with attached video loops are included. Includes image sticker URL arrays, animated_stickers grouped by sticker ID with telegram, whatsapp, wechat and discord URL keys in formats, and complete cursor-follower interactions with nine WebP frame URLs and a JSON manifest URL. Only completed, non-archived hosted assets are included. Create cursor followers with POST /v1/collections/{id}/interactive. Use the raw items and assets endpoints for IDs, prompts, metadata, and status checks. Returns 409 cdn_export_not_ready while asset hosting is off (turn it on with POST /v1/collections/{id}/publish after the owner agrees) or before any file is hosted. No credit cost.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

Responses

200 Collection CDN export JSON

application/json

collectionstring · required

itemsarray · required

Nested fields

namestring · required

svgstring · uri

imagestring · uri

transparent_imagestring · uri

animationsarray

Nested fields

object

logosobject

stickersarray

Nested fields

string

animated_stickersarray

Nested fields

idstring · uuid · required

source_asset_idstring · uuid · required

formatsobject · required

Nested fields

telegramstring · uri

whatsappstring · uri

wechatstring · uri

discordstring · uri

interactionsarray

Nested fields

versionnumber · required

Values: 1

idstring · uuid · required

namestring · required

kindstring · required

Values: "cursor-follower"

widthnumber · required

Values: 1024

heightnumber · required

Values: 1024

framesobject · required

Nested fields

up-leftstring · uri · required

upstring · uri · required

up-rightstring · uri · required

leftstring · uri · required

centerstring · uri · required

rightstring · uri · required

down-leftstring · uri · required

downstring · uri · required

down-rightstring · uri · required

manifest_urlstring · uri · required

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 CDN export is not ready

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Collections"
  ],
  "summary": "Export published CDN links",
  "description": "Returns the same clean hosted-link JSON shown in the collection page Get Links export modal. This endpoint is built from published CDN assets, not raw item types, so pose/image items with attached video loops are included. Includes image sticker URL arrays, animated_stickers grouped by sticker ID with telegram, whatsapp, wechat and discord URL keys in formats, and complete cursor-follower interactions with nine WebP frame URLs and a JSON manifest URL. Only completed, non-archived hosted assets are included. Create cursor followers with POST /v1/collections/{id}/interactive. Use the raw items and assets endpoints for IDs, prompts, metadata, and status checks. Returns 409 cdn_export_not_ready while asset hosting is off (turn it on with POST /v1/collections/{id}/publish after the owner agrees) or before any file is hosted. No credit cost.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    }
  ],
  "responses": {
    "200": {
      "description": "Collection CDN export JSON",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CdnExportResponse"
          },
          "example": {
            "collection": "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",
                    "transparent_video_android_360": "https://assets.masko.ai/fda8417d/fox-mascot/card-sit-360.mp4"
                  }
                ],
                "animated_stickers": [
                  {
                    "id": "22222222-2222-4222-8222-222222222222",
                    "source_asset_id": "33333333-3333-4333-8333-333333333333",
                    "formats": {
                      "telegram": "https://assets.masko.ai/fda8417d/fox-mascot/card-sit-sticker.webm",
                      "whatsapp": "https://assets.masko.ai/fda8417d/fox-mascot/card-sit-sticker.webp",
                      "wechat": "https://assets.masko.ai/fda8417d/fox-mascot/card-sit-sticker.gif",
                      "discord": "https://assets.masko.ai/fda8417d/fox-mascot/card-sit-sticker.png"
                    }
                  }
                ]
              }
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "409": {
      "description": "CDN export is not ready",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    }
  },
  "deprecated": true,
  "operationId": "legacyGetCollectionCdnExport"
}

POST/v1/collections/{id}/publishTurn on asset hosting

Turns on asset hosting for this mascot, the same switch as Get Links in Studio. Every finished image and video gets a permanent public URL on assets.masko.ai, and files finished later are hosted automatically. Anyone with a URL can open the file, so confirm with the mascot owner before calling it. Mascots created with the API start with hosting on (settings.cdn_enabled); mascots made in Studio or through the MCP server start with it off. Calling it again on a hosted mascot changes nothing and returns changed: false with the current URLs; pass force: true to host missing finished files or refresh them. Changing the slug of a hosted mascot requires force: true, otherwise 409. Returns 400 when the mascot has no finished file yet. Afterwards GET /v1/collections/{id}/cdn-export lists every hosted link. No generation credits; hosting is free up to 50,000 views a month, then 1 credit per 1,000 views.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

Idempotency-Keyheader

string

Request body

Optional. Send {} or no body to use the current slug.

application/json

slugstring

Optional CDN slug. If omitted, the existing slug or generated collection slug is used.

Length: 2 to 50 characters

forceboolean

Republish even if CDN rows already exist. Use this to backfill or refresh CDN assets after a partial publish.

Default: false

Responses

200 Asset hosting is on

application/json

dataobject · required

Nested fields

successboolean · required

collection_idstring · uuid · required

public_slugstring · required

user_prefixstring · nullable · required

cdn_asset_countinteger · required

Range: 0 to unbounded

publishedboolean · required

Values: true

changedboolean · required

False when the mascot was already hosted and nothing was published.

public_urlsobject · nullable · required

Hosted URLs by item slug, then by format key (webm, hevc, image, transparent_image, size variants such as webm_360).

Nested fields

basestring · required

itemsobject · required

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Collections"
  ],
  "summary": "Turn on asset hosting",
  "description": "Turns on asset hosting for this mascot, the same switch as Get Links in Studio. Every finished image and video gets a permanent public URL on assets.masko.ai, and files finished later are hosted automatically. Anyone with a URL can open the file, so confirm with the mascot owner before calling it. Mascots created with the API start with hosting on (settings.cdn_enabled); mascots made in Studio or through the MCP server start with it off. Calling it again on a hosted mascot changes nothing and returns changed: false with the current URLs; pass force: true to host missing finished files or refresh them. Changing the slug of a hosted mascot requires force: true, otherwise 409. Returns 400 when the mascot has no finished file yet. Afterwards GET /v1/collections/{id}/cdn-export lists every hosted link. No generation credits; hosting is free up to 50,000 views a month, then 1 credit per 1,000 views.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.",
      "schema": {
        "type": "string",
        "maxLength": 255
      }
    }
  ],
  "requestBody": {
    "required": false,
    "description": "Optional. Send {} or no body to use the current slug.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/PublishCollectionBody"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Asset hosting is on",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PublishCollectionResponse"
          },
          "example": {
            "data": {
              "success": true,
              "collection_id": "f9503022-a991-46ea-bf8c-d628c921b6b0",
              "public_slug": "fox-mascot-f950",
              "user_prefix": "fda841",
              "cdn_asset_count": 12,
              "published": true,
              "changed": true,
              "public_urls": {
                "base": "https://assets.masko.ai/fda841/fox-mascot-f950",
                "items": {
                  "card-sit": {
                    "image": "https://assets.masko.ai/fda841/fox-mascot-f950/card-sit.png",
                    "webm": "https://assets.masko.ai/fda841/fox-mascot-f950/card-sit.webm",
                    "hevc": "https://assets.masko.ai/fda841/fox-mascot-f950/card-sit.mov"
                  }
                }
              }
            }
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    }
  },
  "deprecated": true,
  "operationId": "legacyPublishCollection"
}

GET/v1/assetsList assets across all collections

Returns paginated assets spanning every mascot owned by the caller, each annotated with its mascot_id. Filter by type, status, or mascot_id. Set include_file_urls=false for faster metadata-only listings. No credit cost.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

limitquery

Page size. 1 to 100. Defaults to 50.

number

offsetquery

Number of records to skip. Defaults to 0.

number

cursorquery

Opaque next_cursor from the previous page. Use instead of offset.

string

mascot_idquery

Filter to a single mascot. Omit to list across all of your mascots.

string

typequery

Filter by asset type: image, transparent_image, video, webm, hevc, stacked_video, svg, etc.

string

is_archivedquery

Include archived assets. Defaults to false (active only).

string · true, false

item_idquery

Filter to a single item within a mascot.

string

include_file_urlsquery

Whether to include signed file_url values. Defaults to true. Set false for faster metadata-only listings.

string · true, false

Masko-API-Versionheader

Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract.

string · 2026-09-26, legacy

api_versionquery

Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree.

string · 2026-09-26, legacy

collection_idquery

Legacy-only filter. Use mascot_id for new clients; never send both.

string

Responses

200 List of assets across your collections

application/json

StudioAssetListResponse

dataarray · required

Nested fields

objectstring

Resource type. Always "asset".

Values: "asset"

idstring · uuid · required

typestring · required

Values: "interactive", "interactive_frame", "image", "transparent_image", "sticker_image", "svg", "video", "webm", "hevc", "stacked_video", "stacked_video_av1", "logo", "audio", "transcript"

statusstring · required

metadataobject · nullable

Media dimensions, format and public asset context. Internal generation execution details are omitted.

item_idstring · uuid · nullable · required

mascot_idstring · uuid · nullable

file_urlstring · uri · nullable · required

cdn_urlstring · uri · nullable · required

file_sizeinteger · nullable

Size of the file in bytes; null until the file is completed, or when it cannot be read.

is_archivedboolean

archived_atstring · nullable

created_atstring · required

metaobject · required

Nested fields

paginationobject

Nested fields

totalinteger · required

Range: 0 to unbounded

limitinteger · required

Range: 0 to unbounded

offsetinteger · required

Range: 0 to unbounded

has_moreboolean · required

next_cursorstring · nullable

Pass as the cursor query parameter to get the next page. Null on the last page.

AssetListResponse

dataarray · required

Nested fields

objectstring

Resource type. Always "asset".

Values: "asset"

idstring · uuid · required

typestring · required

Values: "interactive", "interactive_frame", "image", "transparent_image", "sticker_image", "svg", "video", "webm", "hevc", "stacked_video", "stacked_video_av1", "logo", "audio", "transcript"

statusstring · required

metadataobject · nullable

Media dimensions, format and public asset context. Internal generation execution details are omitted.

item_idstring · uuid · nullable · required

collection_idstring · uuid · nullable

file_urlstring · uri · nullable · required

cdn_urlstring · uri · nullable · required

file_sizeinteger · nullable

Size of the file in bytes; null until the file is completed, or when it cannot be read.

is_archivedboolean

archived_atstring · nullable

created_atstring · required

metaobject · required

Nested fields

paginationobject

Nested fields

totalinteger · required

Range: 0 to unbounded

limitinteger · required

Range: 0 to unbounded

offsetinteger · required

Range: 0 to unbounded

has_moreboolean · required

next_cursorstring · nullable

Pass as the cursor query parameter to get the next page. Null on the last page.

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Assets"
  ],
  "summary": "List assets across all collections",
  "description": "Returns paginated assets spanning every mascot owned by the caller, each annotated with its `mascot_id`. Filter by `type`, `status`, or `mascot_id`. Set `include_file_urls=false` for faster metadata-only listings. No credit cost.\n\nSelect Masko-API-Version: 2026-09-26 (or api_version=2026-09-26) for the canonical mascot contract shown first. Existing unversioned clients keep legacy collection fields. A mascot_id query filter also selects the canonical contract. Mixing identifier names returns 400.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "number",
        "minimum": 1,
        "maximum": 100,
        "default": 50,
        "description": "Page size. 1 to 100. Defaults to 50."
      },
      "required": false,
      "description": "Page size. 1 to 100. Defaults to 50.",
      "name": "limit",
      "in": "query"
    },
    {
      "schema": {
        "type": "number",
        "nullable": true,
        "minimum": 0,
        "default": 0,
        "description": "Number of records to skip. Defaults to 0."
      },
      "required": false,
      "description": "Number of records to skip. Defaults to 0.",
      "name": "offset",
      "in": "query"
    },
    {
      "schema": {
        "type": "string",
        "description": "Opaque next_cursor from the previous page. Use instead of offset."
      },
      "required": false,
      "description": "Opaque next_cursor from the previous page. Use instead of offset.",
      "name": "cursor",
      "in": "query"
    },
    {
      "schema": {
        "type": "string",
        "format": "uuid",
        "description": "Filter to a single mascot. Omit to list across all of your mascots."
      },
      "required": false,
      "description": "Filter to a single mascot. Omit to list across all of your mascots.",
      "name": "mascot_id",
      "in": "query"
    },
    {
      "schema": {
        "type": "string",
        "description": "Filter by asset type: image, transparent_image, video, webm, hevc, stacked_video, svg, etc."
      },
      "required": false,
      "description": "Filter by asset type: image, transparent_image, video, webm, hevc, stacked_video, svg, etc.",
      "name": "type",
      "in": "query"
    },
    {
      "schema": {
        "type": "string",
        "enum": [
          "true",
          "false"
        ],
        "description": "Include archived assets. Defaults to false (active only)."
      },
      "required": false,
      "description": "Include archived assets. Defaults to false (active only).",
      "name": "is_archived",
      "in": "query"
    },
    {
      "schema": {
        "type": "string",
        "format": "uuid",
        "description": "Filter to a single item within a mascot."
      },
      "required": false,
      "description": "Filter to a single item within a mascot.",
      "name": "item_id",
      "in": "query"
    },
    {
      "schema": {
        "type": "string",
        "enum": [
          "true",
          "false"
        ],
        "description": "Whether to include signed file_url values. Defaults to true. Set false for faster metadata-only listings."
      },
      "required": false,
      "description": "Whether to include signed file_url values. Defaults to true. Set false for faster metadata-only listings.",
      "name": "include_file_urls",
      "in": "query"
    },
    {
      "in": "header",
      "name": "Masko-API-Version",
      "required": false,
      "schema": {
        "type": "string",
        "enum": [
          "2026-09-26",
          "legacy"
        ]
      },
      "description": "Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract."
    },
    {
      "in": "query",
      "name": "api_version",
      "required": false,
      "schema": {
        "type": "string",
        "enum": [
          "2026-09-26",
          "legacy"
        ]
      },
      "description": "Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree."
    },
    {
      "schema": {
        "type": "string",
        "format": "uuid",
        "description": "Filter to a single mascot. Omit to list across all of your mascots."
      },
      "required": false,
      "description": "Legacy-only filter. Use mascot_id for new clients; never send both.",
      "name": "collection_id",
      "in": "query",
      "deprecated": true
    }
  ],
  "responses": {
    "200": {
      "description": "List of assets across your collections",
      "content": {
        "application/json": {
          "schema": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/StudioAssetListResponse"
              },
              {
                "$ref": "#/components/schemas/AssetListResponse"
              }
            ]
          },
          "example": {
            "data": [
              {
                "id": "5114bec3-b92a-4917-8675-84fce713d3cf",
                "type": "image",
                "status": "completed",
                "metadata": {},
                "item_id": null,
                "mascot_id": "f9503022-a991-46ea-bf8c-d628c921b6b0",
                "file_url": "https://storage.googleapis.com/masco-media/...signed-url...",
                "cdn_url": null,
                "created_at": "2026-04-19T09:36:46.95543+00:00"
              }
            ],
            "meta": {
              "pagination": {
                "total": 215,
                "limit": 3,
                "offset": 0,
                "has_more": true
              }
            }
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    }
  },
  "operationId": "listAssets"
}

GET/v1/assets/{id}Get asset details

Returns a single asset record with its signed file_url and optional cdn_url. Returns 404 if the asset is not owned by the caller. No credit cost.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

Masko-API-Versionheader

Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract.

string · 2026-09-26, legacy

api_versionquery

Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree.

string · 2026-09-26, legacy

Responses

200 Asset details

application/json

StudioAssetResponse

dataobject · required

Nested fields

objectstring

Resource type. Always "asset".

Values: "asset"

idstring · uuid · required

typestring · required

Values: "interactive", "interactive_frame", "image", "transparent_image", "sticker_image", "svg", "video", "webm", "hevc", "stacked_video", "stacked_video_av1", "logo", "audio", "transcript"

statusstring · required

metadataobject · nullable

Media dimensions, format and public asset context. Internal generation execution details are omitted.

item_idstring · uuid · nullable · required

mascot_idstring · uuid · nullable

file_urlstring · uri · nullable · required

cdn_urlstring · uri · nullable · required

file_sizeinteger · nullable

Size of the file in bytes; null until the file is completed, or when it cannot be read.

is_archivedboolean

archived_atstring · nullable

created_atstring · required

AssetResponse

dataobject · required

Nested fields

objectstring

Resource type. Always "asset".

Values: "asset"

idstring · uuid · required

typestring · required

Values: "interactive", "interactive_frame", "image", "transparent_image", "sticker_image", "svg", "video", "webm", "hevc", "stacked_video", "stacked_video_av1", "logo", "audio", "transcript"

statusstring · required

metadataobject · nullable

Media dimensions, format and public asset context. Internal generation execution details are omitted.

item_idstring · uuid · nullable · required

collection_idstring · uuid · nullable

file_urlstring · uri · nullable · required

cdn_urlstring · uri · nullable · required

file_sizeinteger · nullable

Size of the file in bytes; null until the file is completed, or when it cannot be read.

is_archivedboolean

archived_atstring · nullable

created_atstring · required

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Assets"
  ],
  "summary": "Get asset details",
  "description": "Returns a single asset record with its signed `file_url` and optional `cdn_url`. Returns 404 if the asset is not owned by the caller. No credit cost.\n\nSelect Masko-API-Version: 2026-09-26 (or api_version=2026-09-26) for the canonical mascot contract shown first. Existing unversioned clients keep legacy collection fields. A mascot_id query filter also selects the canonical contract. Mixing identifier names returns 400.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "in": "header",
      "name": "Masko-API-Version",
      "required": false,
      "schema": {
        "type": "string",
        "enum": [
          "2026-09-26",
          "legacy"
        ]
      },
      "description": "Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract."
    },
    {
      "in": "query",
      "name": "api_version",
      "required": false,
      "schema": {
        "type": "string",
        "enum": [
          "2026-09-26",
          "legacy"
        ]
      },
      "description": "Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree."
    }
  ],
  "responses": {
    "200": {
      "description": "Asset details",
      "content": {
        "application/json": {
          "schema": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/StudioAssetResponse"
              },
              {
                "$ref": "#/components/schemas/AssetResponse"
              }
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    }
  },
  "operationId": "getAsset"
}

DELETE/v1/assets/{id}Archive an asset

Soft-deletes (archives) a single asset. The underlying file is retained on storage but filtered from reads. Returns 204 on success. No credit cost.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

Masko-API-Versionheader

Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract.

string · 2026-09-26, legacy

api_versionquery

Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree.

string · 2026-09-26, legacy

Responses

204 Archived

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Assets"
  ],
  "summary": "Archive an asset",
  "description": "Soft-deletes (archives) a single asset. The underlying file is retained on storage but filtered from reads. Returns 204 on success. No credit cost.\n\nSelect Masko-API-Version: 2026-09-26 (or api_version=2026-09-26) for the canonical mascot contract shown first. Existing unversioned clients keep legacy collection fields. A mascot_id query filter also selects the canonical contract. Mixing identifier names returns 400.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "in": "header",
      "name": "Masko-API-Version",
      "required": false,
      "schema": {
        "type": "string",
        "enum": [
          "2026-09-26",
          "legacy"
        ]
      },
      "description": "Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract."
    },
    {
      "in": "query",
      "name": "api_version",
      "required": false,
      "schema": {
        "type": "string",
        "enum": [
          "2026-09-26",
          "legacy"
        ]
      },
      "description": "Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree."
    }
  ],
  "responses": {
    "204": {
      "description": "Archived",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    }
  },
  "operationId": "deleteAsset"
}

POST/v1/assets/{id}/stickerCreate a sticker from an image or animation

Image: generates transparent sticker artwork for 1 credit and returns the existing 201 image receipt. Animation: creates one sticker_animation library asset and automatically prepares Telegram, WhatsApp, WeChat and Discord files in a CPU batch using its saved video and mask, for zero generation credits. Requires a completed video/webm/hevc with a background-removal result. Reuses the same sticker and valid cached files. Omit the body or send {}. force:true regenerates completed platform exports. Returns 202 while preparing, otherwise 200. Poll GET /v1/assets/{sticker_id}/sticker. Each format includes a validated file_url and a public_url when mascot asset hosting is enabled. Platform failures are independent.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

Idempotency-Keyheader

string

Masko-API-Versionheader

Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract.

string · 2026-09-26, legacy

api_versionquery

Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree.

string · 2026-09-26, legacy

Request body

application/json

forceboolean

Default: false

Responses

200 Reused prepared animated sticker

application/json

dataobject · required

Nested fields

idstring · uuid · required

objectstring · required

Values: "animated_sticker"

source_asset_idstring · uuid · required

asset_idsobject · required

Nested fields

sticker_animationstring · uuid · required

statusstring · required

Values: "processing", "completed", "partial_failure", "failed"

estimated_costnumber · required

Values: 0

asset_hostingboolean · required

preview_urlstring · nullable · required

preview_typestring · required

poll_urlstring · required

formatsarray · required

Items: 4 to 4

Nested fields

idstring · uuid · required

source_asset_idstring · uuid · required

formatstring · required

sizenumber · nullable · required

job_idstring · uuid · required

asset_idstring · uuid · required

statusstring · required

Values: "pending", "processing", "completed", "failed"

errorstring · nullable · required

file_urlstring · nullable · required

public_urlstring · nullable · required

metadataobject · nullable

sticker_profilestring

poster_urlstring · nullable

poll_urlstring · required

201 Sticker generated

application/json

dataobject · required

Nested fields

job_idstring · uuid · required

statusstring · required

Values: "completed"

source_asset_idstring · uuid · required

asset_idsobject · required

Nested fields

sticker_imagestring · uuid · required

estimated_costnumber · required

sticker_imageobject · required

Nested fields

idstring · uuid · required

typestring · required

Values: "sticker_image"

statusstring · required

Values: "completed"

file_urlstring · uri · required

widthinteger · nullable

Range: 0 to unbounded

heightinteger · nullable

Range: 0 to unbounded

202 Animated sticker created; platform files preparing

application/json

dataobject · required

Nested fields

idstring · uuid · required

objectstring · required

Values: "animated_sticker"

source_asset_idstring · uuid · required

asset_idsobject · required

Nested fields

sticker_animationstring · uuid · required

statusstring · required

Values: "processing", "completed", "partial_failure", "failed"

estimated_costnumber · required

Values: 0

asset_hostingboolean · required

preview_urlstring · nullable · required

preview_typestring · required

poll_urlstring · required

formatsarray · required

Items: 4 to 4

Nested fields

idstring · uuid · required

source_asset_idstring · uuid · required

formatstring · required

sizenumber · nullable · required

job_idstring · uuid · required

asset_idstring · uuid · required

statusstring · required

Values: "pending", "processing", "completed", "failed"

errorstring · nullable · required

file_urlstring · nullable · required

public_urlstring · nullable · required

metadataobject · nullable

sticker_profilestring

poster_urlstring · nullable

poll_urlstring · required

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Assets"
  ],
  "summary": "Create a sticker from an image or animation",
  "description": "Image: generates transparent sticker artwork for 1 credit and returns the existing 201 image receipt. Animation: creates one sticker_animation library asset and automatically prepares Telegram, WhatsApp, WeChat and Discord files in a CPU batch using its saved video and mask, for zero generation credits. Requires a completed video/webm/hevc with a background-removal result. Reuses the same sticker and valid cached files. Omit the body or send {}. force:true regenerates completed platform exports. Returns 202 while preparing, otherwise 200. Poll GET /v1/assets/{sticker_id}/sticker. Each format includes a validated file_url and a public_url when mascot asset hosting is enabled. Platform failures are independent.\n\nSelect Masko-API-Version: 2026-09-26 (or api_version=2026-09-26) for the canonical mascot contract shown first. Existing unversioned clients keep legacy collection fields. A mascot_id query filter also selects the canonical contract. Mixing identifier names returns 400.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.",
      "schema": {
        "type": "string",
        "maxLength": 255
      }
    },
    {
      "in": "header",
      "name": "Masko-API-Version",
      "required": false,
      "schema": {
        "type": "string",
        "enum": [
          "2026-09-26",
          "legacy"
        ]
      },
      "description": "Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract."
    },
    {
      "in": "query",
      "name": "api_version",
      "required": false,
      "schema": {
        "type": "string",
        "enum": [
          "2026-09-26",
          "legacy"
        ]
      },
      "description": "Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree."
    }
  ],
  "requestBody": {
    "required": false,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/AnimatedStickerCreateBody"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Reused prepared animated sticker",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/AnimatedStickerReceipt"
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "201": {
      "description": "Sticker generated",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/StickerGenerateResponse"
          },
          "example": {
            "data": {
              "job_id": "8c458fc7-df42-4e5a-b5cb-8768c4d9f4a1",
              "status": "completed",
              "source_asset_id": "5114bec3-b92a-4917-8675-84fce713d3cf",
              "asset_ids": {
                "sticker_image": "bafc3f5e-e90c-4cf8-88c2-bb5bcf3c5088"
              },
              "estimated_cost": 1,
              "sticker_image": {
                "id": "bafc3f5e-e90c-4cf8-88c2-bb5bcf3c5088",
                "type": "sticker_image",
                "status": "completed",
                "file_url": "https://storage.googleapis.com/masco-media/...signed-url...",
                "width": 1024,
                "height": 1024
              }
            }
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "202": {
      "description": "Animated sticker created; platform files preparing",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/AnimatedStickerReceipt"
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    }
  },
  "operationId": "stickerAsset"
}

GET/v1/assets/{id}/stickerGet an animated sticker and its platform files

Use the sticker_animation asset ID returned by creation. Reports each platform independently, including signed or hosted file_url and public_url. A partial_failure keeps successful platform files usable. Public URLs require asset hosting. No credit charge.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

Masko-API-Versionheader

Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract.

string · 2026-09-26, legacy

api_versionquery

Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree.

string · 2026-09-26, legacy

Responses

200 Animated sticker

application/json

dataobject · required

Nested fields

idstring · uuid · required

objectstring · required

Values: "animated_sticker"

source_asset_idstring · uuid · required

asset_idsobject · required

Nested fields

sticker_animationstring · uuid · required

statusstring · required

Values: "processing", "completed", "partial_failure", "failed"

estimated_costnumber · required

Values: 0

asset_hostingboolean · required

preview_urlstring · nullable · required

preview_typestring · required

poll_urlstring · required

formatsarray · required

Items: 4 to 4

Nested fields

idstring · uuid · required

source_asset_idstring · uuid · required

formatstring · required

sizenumber · nullable · required

job_idstring · uuid · required

asset_idstring · uuid · required

statusstring · required

Values: "pending", "processing", "completed", "failed"

errorstring · nullable · required

file_urlstring · nullable · required

public_urlstring · nullable · required

metadataobject · nullable

sticker_profilestring

poster_urlstring · nullable

poll_urlstring · required

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Assets"
  ],
  "summary": "Get an animated sticker and its platform files",
  "description": "Use the sticker_animation asset ID returned by creation. Reports each platform independently, including signed or hosted file_url and public_url. A partial_failure keeps successful platform files usable. Public URLs require asset hosting. No credit charge.\n\nSelect Masko-API-Version: 2026-09-26 (or api_version=2026-09-26) for the canonical mascot contract shown first. Existing unversioned clients keep legacy collection fields. A mascot_id query filter also selects the canonical contract. Mixing identifier names returns 400.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "in": "header",
      "name": "Masko-API-Version",
      "required": false,
      "schema": {
        "type": "string",
        "enum": [
          "2026-09-26",
          "legacy"
        ]
      },
      "description": "Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract."
    },
    {
      "in": "query",
      "name": "api_version",
      "required": false,
      "schema": {
        "type": "string",
        "enum": [
          "2026-09-26",
          "legacy"
        ]
      },
      "description": "Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree."
    }
  ],
  "responses": {
    "200": {
      "description": "Animated sticker",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/AnimatedStickerReceipt"
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    }
  },
  "operationId": "getAssetSticker"
}

POST/v1/assets/{id}/refine-maskRefine a video asset mask

Refines the active background mask for a completed video asset, then re-exports the requested derived formats and sizes from the refined mask. Omit formats and sizes to infer the currently active linked variants and refresh all of them. Old matching derived assets are archived and unlinked only after replacement assets are successfully published. Defaults to dry_run=true so agents can inspect the exact plan before starting the workflow.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

Idempotency-Keyheader

string

Masko-API-Versionheader

Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract.

string · 2026-09-26, legacy

api_versionquery

Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree.

string · 2026-09-26, legacy

Request body (required)

Request body

application/json

opstring

Mask operation. add unions the prompted subject into the active mask; subtract removes it from the active mask.

Values: "add", "subtract"

Default: "add"

promptstring · required

Text prompt for the mask region to refine, e.g. "the soccer ball".

Length: 1 to unbounded characters

modelstring

Background mask refinement quality. Defaults to pro.

Values: "original", "pro"

Default: "pro"

edge_cleanupobject

Optional edge cleanup pass applied to the refined mask.

Default: {"enabled":true,"size":512}

Nested fields

enabledboolean

Default: true

sizeinteger

Default: 512

Range: 128 to 1024

formatsarray

Derived formats to regenerate. Omit to infer the active formats already linked to the video.

Items: 1 to unbounded

Nested fields

string · webm, hevc, stacked_video, lottie, dotlottie

sizesarray

Size variants to regenerate. Omit to infer active linked sizes, so all currently used variants are refreshed.

Nested fields

integer

archive_oldboolean

Archive and unlink old matching derived assets after replacement assets are successfully published.

Default: true

dry_runboolean

Return the exact refinement/export plan without starting the workflow.

Default: true

Responses

200 Mask refinement dry-run plan returned

application/json

StudioAssetMaskRefinementResponse

dataobject · required

Nested fields

targetstring · required

Values: "video_mask_refinement"

dry_runboolean · required

video_asset_idstring · uuid · required

bg_job_idstring · required

promptstring · required

opstring · required

Values: "add", "subtract"

modelstring · required

Values: "original", "pro"

edge_cleanupobject

Nested fields

enabledboolean · required

sizenumber · required

formatsarray · required

Nested fields

string · webm, hevc, stacked_video, lottie, dotlottie

sizesarray · required

Nested fields

number

export_countnumber · required

archive_oldboolean · required

active_variantsarray · required

Nested fields

idstring · uuid · required

typestring · required

sizenumber

bgJobIdstring

canvasobject

Nested fields

mascot_idstring · uuid

canvasIdstring · uuid

edgeIdstring

in_flightobject

Nested fields

job_idstring · uuid · required

poll_urlstring · required

job_idstring · uuid

poll_urlstring

AssetMaskRefinementResponse

dataobject · required

Nested fields

targetstring · required

Values: "video_mask_refinement"

dry_runboolean · required

video_asset_idstring · uuid · required

bg_job_idstring · required

promptstring · required

opstring · required

Values: "add", "subtract"

modelstring · required

Values: "original", "pro"

edge_cleanupobject

Nested fields

enabledboolean · required

sizenumber · required

formatsarray · required

Nested fields

string · webm, hevc, stacked_video, lottie, dotlottie

sizesarray · required

Nested fields

number

export_countnumber · required

archive_oldboolean · required

active_variantsarray · required

Nested fields

idstring · uuid · required

typestring · required

sizenumber

bgJobIdstring

canvasobject

Nested fields

collectionIdstring · uuid

canvasIdstring · uuid

edgeIdstring

in_flightobject

Nested fields

job_idstring · uuid · required

poll_urlstring · required

job_idstring · uuid

poll_urlstring

202 Mask refinement job started

application/json

StudioAssetMaskRefinementResponse

dataobject · required

Nested fields

targetstring · required

Values: "video_mask_refinement"

dry_runboolean · required

video_asset_idstring · uuid · required

bg_job_idstring · required

promptstring · required

opstring · required

Values: "add", "subtract"

modelstring · required

Values: "original", "pro"

edge_cleanupobject

Nested fields

enabledboolean · required

sizenumber · required

formatsarray · required

Nested fields

string · webm, hevc, stacked_video, lottie, dotlottie

sizesarray · required

Nested fields

number

export_countnumber · required

archive_oldboolean · required

active_variantsarray · required

Nested fields

idstring · uuid · required

typestring · required

sizenumber

bgJobIdstring

canvasobject

Nested fields

mascot_idstring · uuid

canvasIdstring · uuid

edgeIdstring

in_flightobject

Nested fields

job_idstring · uuid · required

poll_urlstring · required

job_idstring · uuid

poll_urlstring

AssetMaskRefinementResponse

dataobject · required

Nested fields

targetstring · required

Values: "video_mask_refinement"

dry_runboolean · required

video_asset_idstring · uuid · required

bg_job_idstring · required

promptstring · required

opstring · required

Values: "add", "subtract"

modelstring · required

Values: "original", "pro"

edge_cleanupobject

Nested fields

enabledboolean · required

sizenumber · required

formatsarray · required

Nested fields

string · webm, hevc, stacked_video, lottie, dotlottie

sizesarray · required

Nested fields

number

export_countnumber · required

archive_oldboolean · required

active_variantsarray · required

Nested fields

idstring · uuid · required

typestring · required

sizenumber

bgJobIdstring

canvasobject

Nested fields

collectionIdstring · uuid

canvasIdstring · uuid

edgeIdstring

in_flightobject

Nested fields

job_idstring · uuid · required

poll_urlstring · required

job_idstring · uuid

poll_urlstring

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Assets"
  ],
  "summary": "Refine a video asset mask",
  "description": "Refines the active background mask for a completed video asset, then re-exports the requested derived formats and sizes from the refined mask. Omit `formats` and `sizes` to infer the currently active linked variants and refresh all of them. Old matching derived assets are archived and unlinked only after replacement assets are successfully published. Defaults to `dry_run=true` so agents can inspect the exact plan before starting the workflow.\n\nSelect Masko-API-Version: 2026-09-26 (or api_version=2026-09-26) for the canonical mascot contract shown first. Existing unversioned clients keep legacy collection fields. A mascot_id query filter also selects the canonical contract. Mixing identifier names returns 400.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.",
      "schema": {
        "type": "string",
        "maxLength": 255
      }
    },
    {
      "in": "header",
      "name": "Masko-API-Version",
      "required": false,
      "schema": {
        "type": "string",
        "enum": [
          "2026-09-26",
          "legacy"
        ]
      },
      "description": "Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract."
    },
    {
      "in": "query",
      "name": "api_version",
      "required": false,
      "schema": {
        "type": "string",
        "enum": [
          "2026-09-26",
          "legacy"
        ]
      },
      "description": "Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree."
    }
  ],
  "requestBody": {
    "required": true,
    "description": "Request body",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/RefineAssetMaskBody"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Mask refinement dry-run plan returned",
      "content": {
        "application/json": {
          "schema": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/StudioAssetMaskRefinementResponse"
              },
              {
                "$ref": "#/components/schemas/AssetMaskRefinementResponse"
              }
            ]
          },
          "example": {
            "data": {
              "target": "video_mask_refinement",
              "dry_run": true,
              "video_asset_id": "a98ba960-c1b3-4bf5-9e6f-1d57b43c651d",
              "bg_job_id": "5eb2db13-0000-0000-0000-000000000001",
              "prompt": "the soccer ball",
              "op": "add",
              "model": "pro",
              "edge_cleanup": {
                "enabled": true,
                "size": 512
              },
              "formats": [
                "webm",
                "hevc",
                "stacked_video"
              ],
              "sizes": [
                360
              ],
              "export_count": 6,
              "archive_old": true,
              "active_variants": []
            }
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "202": {
      "description": "Mask refinement job started",
      "content": {
        "application/json": {
          "schema": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/StudioAssetMaskRefinementResponse"
              },
              {
                "$ref": "#/components/schemas/AssetMaskRefinementResponse"
              }
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    }
  },
  "operationId": "refineMaskAsset"
}

POST/v1/collections/{id}/referencesAdd a reference image

Adds an image as a collection-scoped style reference (up to 6 references). Pass either url to download and store a new reference, or asset_id to copy an existing uploaded/generated image into this collection when needed. The returned reference_asset_ids are always collection-scoped assets that the app can display and future generations can use. Invalidates the cached style_card, which will be re-extracted on next generation. No credit cost.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

Idempotency-Keyheader

string

Request body (required)

Request body

application/json

asset_idstring · uuid

Asset ID of an existing uploaded or generated image. If the asset is not already scoped to this collection, the API creates a collection-scoped reference copy and stores that copied asset ID in reference_asset_ids.

urlstring · uri

Public HTTP(S) image URL, up to 10 MB with a 15-second download deadline. Private addresses and unsafe redirects are rejected. PNG, JPEG, WebP, GIF and SVG are supported; SVG is converted to PNG. Downloaded and stored as a collection-scoped reference asset.

Responses

201 Reference added

application/json

dataobject · required

Nested fields

reference_asset_idsarray · required

Nested fields

string

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "References"
  ],
  "summary": "Add a reference image",
  "description": "Adds an image as a collection-scoped style reference (up to 6 references). Pass either `url` to download and store a new reference, or `asset_id` to copy an existing uploaded/generated image into this collection when needed. The returned `reference_asset_ids` are always collection-scoped assets that the app can display and future generations can use. Invalidates the cached style_card, which will be re-extracted on next generation. No credit cost.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.",
      "schema": {
        "type": "string",
        "maxLength": 255
      }
    }
  ],
  "requestBody": {
    "required": true,
    "description": "Request body",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/AddReferenceBody"
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Reference added",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ReferenceResponse"
          },
          "example": {
            "data": {
              "reference_asset_ids": [
                "e906ebb5-deb1-4010-82f9-f0182a3812e0",
                "5114bec3-b92a-4917-8675-84fce713d3cf",
                "b357dfe9-92ab-4696-beb3-4f36779808f2"
              ]
            }
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    }
  },
  "deprecated": true,
  "operationId": "legacyCreateCollectionReference"
}

DELETE/v1/collections/{id}/references/{assetId}Remove a reference image

Removes an asset from the collection reference list. Returns the updated reference_asset_ids array. Invalidates the cached style_card. No credit cost.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

assetIdpath · required

string

Responses

200 Reference removed

application/json

dataobject · required

Nested fields

reference_asset_idsarray · required

Nested fields

string

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "References"
  ],
  "summary": "Remove a reference image",
  "description": "Removes an asset from the collection reference list. Returns the updated `reference_asset_ids` array. Invalidates the cached style_card. No credit cost.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "assetId",
      "in": "path"
    }
  ],
  "responses": {
    "200": {
      "description": "Reference removed",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ReferenceResponse"
          },
          "example": {
            "data": {
              "reference_asset_ids": [
                "e906ebb5-deb1-4010-82f9-f0182a3812e0",
                "5114bec3-b92a-4917-8675-84fce713d3cf"
              ]
            }
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    }
  },
  "deprecated": true,
  "operationId": "legacyDeleteCollectionReference"
}

POST/v1/collections/{id}/generateGenerate image or animation

Starts an async generation job. Returns 202 with data.job_id - poll via GET /v1/jobs/{id} (or pass ?wait=true for long-polling). Cost by type: image=1, animation=2/sec with animation_model=standard (2–15s) or 6/sec with animation_model=premium (4–30s), default 5s for either choice (+1 if no source image); omitting animation_model preserves legacy 5/sec, 4–10s, default 4s, logo=5, edit=1 for images, background=3, reverse=0. For type: animation, you can skip providing a source image: pass only animation_prompt (and optionally image_prompt) and the system generates a fresh source image first, then animates it. To animate an uploaded image directly, pass its POST /v1/upload asset_id as source_image_asset_id with type=animation. The upload is imported into the mascot without changing references; no image-generation credits are charged. Existing mascot assets preserve their saved context. Before video generation, non-square starting and ending images are center-cropped to square; square images are reused unchanged. Optional source_image_crop and end_image_crop specify integer x, y, width and height in pixels after image orientation. Cropped copies preserve the originals and incur no extra credits. Invalid crops return 400 before charging. If you have an existing item, pass item_id to animate/edit its current image. For image generation and image edits, pass optional visual_references for one-time pose, expression, motion, prop, style, or scene cues; these references do not become collection mascot references. Backgrounds use this endpoint with type: "background": an empty place in the mascot's own style, with no mascot in it and a spot where its animation plays on top. place sets the shape (phone_screen, phone_header, square, web_hero, banner) and description optionally describes the place; optional source_asset_id selects the mascot picture used as the style sample. To change a background, pass its source_image_asset_id with another place, edit_instructions, or both; the two source fields are mutually exclusive. type: "scene" was replaced by type: "background" and returns 400. Talking animations: pass speech with type: animation and the mascot says the line in its voice (see the Voice endpoints). The length follows the speech, 5 seconds to 5 minutes at 2 credits per second; the receipt charges the longest the line could need and unused seconds are refunded once the voice is recorded. Talking adds audio (MP3) and transcript (JSON) assets. With dry_run: true it returns 200 with the estimate instead. Returns 409 with details.reason voice_required when the mascot has no voice yet. Returns 402 if credits are insufficient.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

Idempotency-Keyheader

string

Request body (required)

Request body

application/json

GenerateImageBody

Generate a static image (pose). Cost: 1 credit.

variant_idstring · uuid

Approved mascot variant for new content. Omit for Original when creating a new pose; when editing an explicit source asset, omission preserves its saved context. Animation loops preserve the generated source pose receipt; an explicit conflicting variant returns 409 unless that variant intentionally includes the source among its references. For transitions, the two poses determine their own before/after contexts. For uploaded references without receipts, a matching selected variant resolves the context; ambiguous shared uploads return 409 before charging. List variants with GET /v1/collections/{id}/variants. Playback activation does not change generation selection.

namestring

Name for the new item. Required when creating a new item. Omit when passing item_id.

item_idstring · uuid

Existing item ID in this collection. Pass this to add a new asset to an existing item, or to animate/edit its current image. For animations and edits, prefer item_id over source_image_asset_id so the API can resolve the source image from the item.

visual_referencesarray

One-time visual references for this generation only. Use for pose, expression, motion, props, style, or scene cues. These do not become collection mascot references and do not update the collection style card.

Items: 0 to 4

Nested fields

asset_idstring · uuid

Existing image asset ID to use as a one-time visual reference.

urlstring · uri

Public image URL to use as a one-time visual reference.

rolestring

What the model should borrow from this image.

Values: "pose", "expression", "motion", "prop", "style", "scene"

notestring

Optional instruction for this reference, e.g. "closed-mouth smile".

Length: 0 to 300 characters

typestring · required

Values: "image"

image_promptstring

What the character is doing in the image, e.g. "waving hello with a big smile".

GenerateAnimationBody

variant_idstring · uuid

namestring

Name for the new item. Required when creating a new item. Omit when passing item_id.

item_idstring · uuid

animation_modelstring

Same choices as Studio: standard costs 2 credits/sec (2–15s); premium costs 6 credits/sec (4–30s). Both default to 5s. Omit to preserve legacy generation at 5 credits/sec (4–10s, default 4s).

Values: "standard", "premium"

durationinteger

Whole seconds. Standard: 2–15; Premium: 4–30; default 5 with either explicit model. Without animation_model: 4–10, default 4. An additional image costs 1 credit only when a source image must be generated.

Range: 2 to 30

typestring · required

Values: "animation"

animation_promptstring

How the character moves, e.g. "bouncing up and down energetically". You can generate an animation directly from just this: when neither item_id nor source_image_asset_id is passed, the system generates a source image first (adds 1 credit), then animates it.

image_promptstring

Used only when no source image exists. The character description that gets passed to image generation before animation starts.

source_image_asset_idstring · uuid

Completed image asset to animate, including an unattached image from POST /v1/upload. Unattached uploads owned by the caller are imported into this mascot without changing references or generating a new image; only animation credits are charged. The original upload is preserved. Non-square inputs are center-cropped to square before animation. Square inputs are reused unchanged. Use source_image_crop for explicit framing. Optional variant_id freezes the selected context for this import. Existing mascot assets retain their saved context. Prefer item_id to reuse an existing item image.

source_image_cropobject

Optional square crop for the starting image: integer x, y, width, height in pixels after EXIF orientation. Defaults to a centered square for non-square images. Requires source_image_asset_id or an item_id with an existing image. Cropping is free and preserves the original file.

Nested fields

xinteger · required

Range: 0 to unbounded

yinteger · required

Range: 0 to unbounded

widthinteger · required

Range: 0 to unbounded

heightinteger · required

Range: 0 to unbounded

end_image_cropobject

Optional square crop for end_image_asset_id, in pixels after EXIF orientation. Defaults to a centered square for non-square end frames. Requires end_image_asset_id.

Nested fields

xinteger · required

Range: 0 to unbounded

yinteger · required

Range: 0 to unbounded

widthinteger · required

Range: 0 to unbounded

heightinteger · required

Range: 0 to unbounded

end_image_asset_idstring · uuid

Target pose image for a transition, including a pose from another variant. The prompt writer uses the starting and ending images plus their separate saved contexts to write the transition direction. The job records both endpoints and the exact prompt under generation_context.transition. Forces loop to false.

loopboolean

Whether the animation loops seamlessly. Defaults to true. Automatically set to false when end_image_asset_id is provided.

reverseboolean

Reverse an existing video. Used with reverse_of_video_asset_id. Costs 0 credits.

reverse_of_video_asset_idstring · uuid

Asset ID of the forward video to reverse. Required when reverse is true.

auto_reverseboolean

Transitions only: also generate the reverse transition (end to source) at 0 extra credits. Requires source_image_asset_id + end_image_asset_id. Response includes a reverse_job field.

reverse_namestring

Name for the auto-generated reverse item. Defaults to "<item name> (Reverse)".

sizesarray

Requested animation size variants in pixels, e.g. [480, 360]. Filtered against the collection settings. No extra credit cost.

Nested fields

integer

speechobject

Makes a talking animation: the mascot says this line in its voice (from its context, or its variant's), starting from item_id or source_image_asset_id and ending on end_image_asset_id (or the start image). The length comes from the speech: 5 seconds to 5 minutes at 2 credits per second. A talk longer than one take (15 seconds) is cut in its pauses into takes that start and end on the start image, then joined. The receipt adds audio and transcript assets and an estimate.

Nested fields

scriptstring

What the mascot says, with movements in square brackets placed where each one starts, e.g. "[waves hello, excited] Hi! I'm Gubby. [points to the right] The docs are right here!". A feeling after a comma also steers the voice.

Length: 1 to 15000 characters

textstring

The words alone, instead of script. Masko writes the movements, following direction when given, and returns the script it used.

Length: 1 to 7500 characters

directionstring

With text: how the mascot should perform the line, e.g. "excited about what he does, points at the docs at the end".

Length: 0 to 500 characters

languagestring

ISO 639-1 code of the line. Omit it to detect the language from the words.

Pattern: ^[a-z]{2}$

dry_runboolean

With speech: return the estimate (and the script, when Masko writes the movements) without charging or generating.

GenerateEditBody

Edit an existing image or video with natural-language instructions. Cost: 1 credit for images, 5 credits per second for videos, rounded up to a whole credit.

variant_idstring · uuid

namestring

Name for the new item. Required when creating a new item. Omit when passing item_id.

item_idstring · uuid

visual_referencesarray

Items: 0 to 4

Nested fields

asset_idstring · uuid

Existing image asset ID to use as a one-time visual reference.

urlstring · uri

Public image URL to use as a one-time visual reference.

rolestring

What the model should borrow from this image.

Values: "pose", "expression", "motion", "prop", "style", "scene"

notestring

Optional instruction for this reference, e.g. "closed-mouth smile".

Length: 0 to 300 characters

typestring · required

Values: "edit"

edit_instructionsstring · required

What to change on the source asset, e.g. "add a santa hat". Required.

source_image_asset_idstring · uuid

Asset ID of the image to edit. Use data.asset_ids.image from a previous /generate response. If you pass item_id, the source is resolved from the item automatically.

source_video_asset_idstring · uuid

Completed 2–15 second video in this collection to edit (H3 Max, 768p before the 720p exports). Duration and aspect ratio are preserved. Uses the source clip and its source item. The edit opens and ends on the poses the clip was made between (a loop on its pose, a transition on its two poses), so it still joins the clips around it; a clip without a saved pose at one end is edited without that frame. For transition clips, edits preserve both saved endpoint identities and their order; variant_id does not restyle the whole clip. The edit prompt is recorded in generation_context.transition_edit.

GenerateLogoBody

Generate a logo master plus a validated transparent version and resized exports. Native alpha is reused when valid; otherwise the transparent version removes the background. The master retains intentional backgrounds. Cost: 5 credits.

variant_idstring · uuid

namestring

Name for the new item. Required when creating a new item. Omit when passing item_id.

item_idstring · uuid

typestring · required

Values: "logo"

request_idstring · uuid

Stable retry key. Requires item_id; reuse unchanged after an uncertain response.

logo_style_idstring

Preset from GET /v1/logo-styles. Explicit style name/instruction override preset fields.

Values: "graphic-app-icon", "cut-paper", "soft-depth", "geometric", "abstract-symbol", "monoline-symbol", "negative-space", "retro-emblem", "hand-drawn"

logo_descriptionstring

What the logo should look like, e.g. "iconic face-only, circular badge". Defaults to "Iconic representation of the character".

logo_style_namestring

Short label for the logo style, e.g. "Flat", "Retro". Defaults to "Flat".

logo_style_instructionstring

Detailed style instructions, e.g. "Flat design with solid colors, no gradients".

GenerateBackgroundBody

Generate a background: an empty place in the mascot's own style, with no mascot in it, calm areas for the app's title and button, and a spot where the mascot's animation plays on top. Or change one with source_image_asset_id. Output: a 4K image. Cost: 3 credits.

variant_idstring · uuid

namestring

Name for the new item. Required when creating a new item. Omit when passing item_id.

item_idstring · uuid

typestring · required

Values: "background"

purposestring

What the background is for: splash, onboarding, signup, home, paywall, reward, empty, loading, landing or banner, or your own words, e.g. "a quiz result page". It sets the default place and is saved with the job. Get five places for it from GET /v1/mascots/{id}/backgrounds/suggestions.

Length: 1 to 120 characters

placestring

Where the background goes, which sets its shape and layout: phone_screen (9:19.5, splash and onboarding), phone_header (10:9, top of a home screen), square (1:1, cards and rewards), web_hero (16:9, top of a landing page) or banner (21:9). For a new background the default comes from purpose, else phone_screen. When changing a background, a new place redraws it in that shape.

Values: "phone_screen", "phone_header", "square", "web_hero", "banner"

descriptionstring

Optional words for the place, e.g. "a quiet meadow under a big sky". Without it the place fits the mascot's style and world.

Length: 0 to 500 characters

source_asset_idstring · uuid

For a new background: a completed picture of the mascot to use as the style sample. Defaults to its first reference. The mascot itself never appears in the background.

source_image_asset_idstring · uuid

To change a background: the background to start from. Pair it with place (another shape), edit_instructions (e.g. "the same place at night"), or both.

edit_instructionsstring

When changing a background: what to change, e.g. "the same place at night".

Length: 0 to 1000 characters

Responses

200 Talking estimate (speech with dry_run)

application/json

dataobject · required

Nested fields

dry_runboolean · required

Values: true

scriptstring · required

estimateobject · required

Talking animations only.

Nested fields

speech_secondsnumber · required

Estimated length of the spoken line.

durationinteger · required

Most likely video length in seconds.

max_durationinteger · required

The longest the video could need; the charge is based on it.

creditsinteger · required

Charged now: max_duration at 2 credits per second. Unused seconds are refunded once the voice is recorded.

too_longboolean · required

202 Generation job started

application/json

dataobject · required

Nested fields

job_idstring · uuid · required

statusstring · required

Values: "pending", "processing", "completed", "failed"

typestring · required

Values: "image", "animation", "edit", "logo", "reverse"

item_idstring · uuid · required

item_namestring · required

estimated_costnumber · required

asset_idsobject

urlsobject

estimateobject

Talking animations only.

Nested fields

speech_secondsnumber · required

Estimated length of the spoken line.

durationinteger · required

Most likely video length in seconds.

max_durationinteger · required

The longest the video could need; the charge is based on it.

creditsinteger · required

Charged now: max_duration at 2 credits per second. Unused seconds are refunded once the voice is recorded.

too_longboolean · required

scriptstring

Talking animations only: the line with its movements, as performed.

poll_urlstring · required

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

402 Insufficient credits

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Generate"
  ],
  "summary": "Generate image or animation",
  "description": "Starts an async generation job. Returns 202 with `data.job_id` - poll via GET `/v1/jobs/{id}` (or pass `?wait=true` for long-polling). Cost by type: image=1, animation=2/sec with animation_model=standard (2–15s) or 6/sec with animation_model=premium (4–30s), default 5s for either choice (+1 if no source image); omitting animation_model preserves legacy 5/sec, 4–10s, default 4s, logo=5, edit=1 for images, background=3, reverse=0. For `type: animation`, you can skip providing a source image: pass only `animation_prompt` (and optionally `image_prompt`) and the system generates a fresh source image first, then animates it. To animate an uploaded image directly, pass its POST /v1/upload asset_id as source_image_asset_id with type=animation. The upload is imported into the mascot without changing references; no image-generation credits are charged. Existing mascot assets preserve their saved context. Before video generation, non-square starting and ending images are center-cropped to square; square images are reused unchanged. Optional source_image_crop and end_image_crop specify integer x, y, width and height in pixels after image orientation. Cropped copies preserve the originals and incur no extra credits. Invalid crops return 400 before charging. If you have an existing item, pass `item_id` to animate/edit its current image. For image generation and image edits, pass optional `visual_references` for one-time pose, expression, motion, prop, style, or scene cues; these references do not become collection mascot references. Backgrounds use this endpoint with `type: \"background\"`: an empty place in the mascot's own style, with no mascot in it and a spot where its animation plays on top. `place` sets the shape (phone_screen, phone_header, square, web_hero, banner) and `description` optionally describes the place; optional `source_asset_id` selects the mascot picture used as the style sample. To change a background, pass its `source_image_asset_id` with another `place`, `edit_instructions`, or both; the two source fields are mutually exclusive. `type: \"scene\"` was replaced by `type: \"background\"` and returns 400. Talking animations: pass `speech` with `type: animation` and the mascot says the line in its voice (see the Voice endpoints). The length follows the speech, 5 seconds to 5 minutes at 2 credits per second; the receipt charges the longest the line could need and unused seconds are refunded once the voice is recorded. Talking adds audio (MP3) and transcript (JSON) assets. With `dry_run: true` it returns 200 with the estimate instead. Returns 409 with details.reason voice_required when the mascot has no voice yet. Returns 402 if credits are insufficient.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.",
      "schema": {
        "type": "string",
        "maxLength": 255
      }
    }
  ],
  "requestBody": {
    "required": true,
    "description": "Request body",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/GenerateBody"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Talking estimate (speech with dry_run)",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/TalkingDryRunResponse"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "202": {
      "description": "Generation job started",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/GenerateAsyncResponse"
          },
          "example": {
            "data": {
              "job_id": "b87c9579-7460-4bd0-aa54-77991615dfef",
              "status": "pending",
              "type": "image",
              "item_id": "e328c567-0965-42fc-90b5-7ff6faa61b25",
              "item_name": "wave",
              "estimated_cost": 1,
              "asset_ids": {
                "image": "a8b158bb-5698-431a-b0f1-98ee30228b11"
              },
              "urls": {
                "transparent_image": "https://assets.masko.ai/fda8417d/cat-api-test-1776591702/wave-91a9ac20.png",
                "image": "https://assets.masko.ai/fda8417d/cat-api-test-1776591702/wave-a8b158bb.png"
              },
              "poll_url": "/api/v1/jobs/b87c9579-7460-4bd0-aa54-77991615dfef"
            }
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "402": {
      "description": "Insufficient credits",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    }
  },
  "deprecated": true,
  "operationId": "legacyGenerateCollection"
}

POST/v1/collections/{id}/animations/reference-videoAnimate a mascot from a reference video

From Video uses Premium to transfer reference motion to your mascot. Upload a video and its first frame through POST /v1/upload, then provide their asset IDs. Source assets must be completed, active, and accessible to the credential; collection assets must belong to its workspace. Creates one animation item plus start and end pose items, with MP4, transparent WebM/HEVC, and pose images. Costs 6 credits per output second plus 1 image credit, so the default 5s costs 31 credits. Output duration is 4–30 whole seconds. Standard is not supported for this operation. Returns 202; poll the returned job until completed. Do not resubmit while the job is running.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

Idempotency-Keyheader

string

Request body (required)

Request body

application/json

video_asset_idstring · uuid · required

Owned, completed video asset containing the reference motion. Upload an MP4 or WebM with POST /v1/upload first.

first_frame_asset_idstring · uuid · required

Owned, completed image asset showing the first frame of the reference video. Upload it with POST /v1/upload.

namestring · required

Name for the animation. Start and end pose items are also created.

Length: 1 to 255 characters

promptstring

Optional instructions for the mascot pose and appearance.

Length: 0 to 10000 characters

durationinteger

Output duration in whole seconds, 4–30. Default 5. Premium costs 6 credits/sec plus 1 image credit.

Default: 5

Range: 4 to 30

animation_modelstring

From Video always uses Premium. Standard is available for image-to-video animation through /generate.

Values: "premium"

Default: "premium"

variant_idstring · uuid

Optional approved mascot variant to animate.

context_asset_idstring · uuid

Optional asset in this collection whose saved mascot context is reused when variant_id is omitted.

Responses

202 Reference video job started

application/json

dataobject · required

Nested fields

job_idstring · uuid · required

item_idstring · uuid · required

start_item_idstring · uuid · required

end_item_idstring · uuid · required

asset_idstring · uuid · required

asset_idsobject · required

Nested fields

mascot_imagestring · uuid · required

videostring · uuid · required

webmstring · uuid · required

hevcstring · uuid · required

start_imagestring · uuid · required

start_transparentstring · uuid · required

end_imagestring · uuid · required

end_transparentstring · uuid · required

estimated_costinteger · required

poll_urlstring · required

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

402 Insufficient credits

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Generate"
  ],
  "summary": "Animate a mascot from a reference video",
  "description": "From Video uses Premium to transfer reference motion to your mascot. Upload a video and its first frame through POST /v1/upload, then provide their asset IDs. Source assets must be completed, active, and accessible to the credential; collection assets must belong to its workspace. Creates one animation item plus start and end pose items, with MP4, transparent WebM/HEVC, and pose images. Costs 6 credits per output second plus 1 image credit, so the default 5s costs 31 credits. Output duration is 4–30 whole seconds. Standard is not supported for this operation. Returns 202; poll the returned job until completed. Do not resubmit while the job is running.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.",
      "schema": {
        "type": "string",
        "maxLength": 255
      }
    }
  ],
  "requestBody": {
    "required": true,
    "description": "Request body",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ReferenceVideoBody"
        }
      }
    }
  },
  "responses": {
    "202": {
      "description": "Reference video job started",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ReferenceVideoAsyncResponse"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "402": {
      "description": "Insufficient credits",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    }
  },
  "deprecated": true,
  "operationId": "legacyCreateCollectionAnimationReferenceVideo"
}

POST/v1/collections/{id}/generate-batchBatch-generate multiple items

Starts multiple generation jobs in one call (up to the per-request cap). Returns 202 with an array of data.jobs[], each with its own job_id. Cost is summed across all items. Returns 402 if credits are insufficient for the whole batch.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

Idempotency-Keyheader

string

Request body (required)

Request body

application/json

requestsarray · required

Up to 10 generate requests run in parallel. Each request follows the same discriminated schema as /generate. Credits are deducted per request. Talking animations (speech) are sent one by one to /generate.

Items: 1 to 10

Nested fields

GenerateImageBody

Generate a static image (pose). Cost: 1 credit.

variant_idstring · uuid

namestring

Name for the new item. Required when creating a new item. Omit when passing item_id.

item_idstring · uuid

visual_referencesarray

Items: 0 to 4

Nested fields

asset_idstring · uuid

Existing image asset ID to use as a one-time visual reference.

urlstring · uri

Public image URL to use as a one-time visual reference.

rolestring

What the model should borrow from this image.

Values: "pose", "expression", "motion", "prop", "style", "scene"

notestring

Optional instruction for this reference, e.g. "closed-mouth smile".

Length: 0 to 300 characters

typestring · required

Values: "image"

image_promptstring

What the character is doing in the image, e.g. "waving hello with a big smile".

GenerateAnimationBody

variant_idstring · uuid

namestring

Name for the new item. Required when creating a new item. Omit when passing item_id.

item_idstring · uuid

animation_modelstring

Same choices as Studio: standard costs 2 credits/sec (2–15s); premium costs 6 credits/sec (4–30s). Both default to 5s. Omit to preserve legacy generation at 5 credits/sec (4–10s, default 4s).

Values: "standard", "premium"

durationinteger

Range: 2 to 30

typestring · required

Values: "animation"

animation_promptstring

image_promptstring

Used only when no source image exists. The character description that gets passed to image generation before animation starts.

source_image_asset_idstring · uuid

source_image_cropobject

Nested fields

xinteger · required

Range: 0 to unbounded

yinteger · required

Range: 0 to unbounded

widthinteger · required

Range: 0 to unbounded

heightinteger · required

Range: 0 to unbounded

end_image_cropobject

Optional square crop for end_image_asset_id, in pixels after EXIF orientation. Defaults to a centered square for non-square end frames. Requires end_image_asset_id.

Nested fields

xinteger · required

Range: 0 to unbounded

yinteger · required

Range: 0 to unbounded

widthinteger · required

Range: 0 to unbounded

heightinteger · required

Range: 0 to unbounded

end_image_asset_idstring · uuid

loopboolean

Whether the animation loops seamlessly. Defaults to true. Automatically set to false when end_image_asset_id is provided.

reverseboolean

Reverse an existing video. Used with reverse_of_video_asset_id. Costs 0 credits.

reverse_of_video_asset_idstring · uuid

Asset ID of the forward video to reverse. Required when reverse is true.

auto_reverseboolean

Transitions only: also generate the reverse transition (end to source) at 0 extra credits. Requires source_image_asset_id + end_image_asset_id. Response includes a reverse_job field.

reverse_namestring

Name for the auto-generated reverse item. Defaults to "<item name> (Reverse)".

sizesarray

Requested animation size variants in pixels, e.g. [480, 360]. Filtered against the collection settings. No extra credit cost.

Nested fields

integer

speechobject

Nested fields

scriptstring

Length: 1 to 15000 characters

textstring

The words alone, instead of script. Masko writes the movements, following direction when given, and returns the script it used.

Length: 1 to 7500 characters

directionstring

With text: how the mascot should perform the line, e.g. "excited about what he does, points at the docs at the end".

Length: 0 to 500 characters

languagestring

ISO 639-1 code of the line. Omit it to detect the language from the words.

Pattern: ^[a-z]{2}$

dry_runboolean

With speech: return the estimate (and the script, when Masko writes the movements) without charging or generating.

GenerateEditBody

Edit an existing image or video with natural-language instructions. Cost: 1 credit for images, 5 credits per second for videos, rounded up to a whole credit.

variant_idstring · uuid

namestring

Name for the new item. Required when creating a new item. Omit when passing item_id.

item_idstring · uuid

visual_referencesarray

Items: 0 to 4

Nested fields

asset_idstring · uuid

Existing image asset ID to use as a one-time visual reference.

urlstring · uri

Public image URL to use as a one-time visual reference.

rolestring

What the model should borrow from this image.

Values: "pose", "expression", "motion", "prop", "style", "scene"

notestring

Optional instruction for this reference, e.g. "closed-mouth smile".

Length: 0 to 300 characters

typestring · required

Values: "edit"

edit_instructionsstring · required

What to change on the source asset, e.g. "add a santa hat". Required.

source_image_asset_idstring · uuid

Asset ID of the image to edit. Use data.asset_ids.image from a previous /generate response. If you pass item_id, the source is resolved from the item automatically.

source_video_asset_idstring · uuid

GenerateLogoBody

variant_idstring · uuid

namestring

Name for the new item. Required when creating a new item. Omit when passing item_id.

item_idstring · uuid

typestring · required

Values: "logo"

request_idstring · uuid

Stable retry key. Requires item_id; reuse unchanged after an uncertain response.

logo_style_idstring

Preset from GET /v1/logo-styles. Explicit style name/instruction override preset fields.

Values: "graphic-app-icon", "cut-paper", "soft-depth", "geometric", "abstract-symbol", "monoline-symbol", "negative-space", "retro-emblem", "hand-drawn"

logo_descriptionstring

What the logo should look like, e.g. "iconic face-only, circular badge". Defaults to "Iconic representation of the character".

logo_style_namestring

Short label for the logo style, e.g. "Flat", "Retro". Defaults to "Flat".

logo_style_instructionstring

Detailed style instructions, e.g. "Flat design with solid colors, no gradients".

GenerateBackgroundBody

variant_idstring · uuid

namestring

Name for the new item. Required when creating a new item. Omit when passing item_id.

item_idstring · uuid

typestring · required

Values: "background"

purposestring

Length: 1 to 120 characters

placestring

Values: "phone_screen", "phone_header", "square", "web_hero", "banner"

descriptionstring

Optional words for the place, e.g. "a quiet meadow under a big sky". Without it the place fits the mascot's style and world.

Length: 0 to 500 characters

source_asset_idstring · uuid

For a new background: a completed picture of the mascot to use as the style sample. Defaults to its first reference. The mascot itself never appears in the background.

source_image_asset_idstring · uuid

To change a background: the background to start from. Pair it with place (another shape), edit_instructions (e.g. "the same place at night"), or both.

edit_instructionsstring

When changing a background: what to change, e.g. "the same place at night".

Length: 0 to 1000 characters

Responses

202 Batch generation jobs started

application/json

dataobject · required

Nested fields

jobsarray · required

Nested fields

job_idstring · uuid · required

statusstring · required

Values: "pending", "processing", "completed", "failed"

typestring · required

Values: "image", "animation", "edit", "logo", "reverse"

item_idstring · uuid · required

item_namestring · required

estimated_costnumber · required

asset_idsobject

urlsobject

estimateobject

Talking animations only.

Nested fields

speech_secondsnumber · required

Estimated length of the spoken line.

durationinteger · required

Most likely video length in seconds.

max_durationinteger · required

The longest the video could need; the charge is based on it.

creditsinteger · required

Charged now: max_duration at 2 credits per second. Unused seconds are refunded once the voice is recorded.

too_longboolean · required

scriptstring

Talking animations only: the line with its movements, as performed.

poll_urlstring · required

total_costnumber · required

poll_urlstring · required

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

402 Insufficient credits

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Generate"
  ],
  "summary": "Batch-generate multiple items",
  "description": "Starts multiple generation jobs in one call (up to the per-request cap). Returns 202 with an array of `data.jobs[]`, each with its own `job_id`. Cost is summed across all items. Returns 402 if credits are insufficient for the whole batch.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.",
      "schema": {
        "type": "string",
        "maxLength": 255
      }
    }
  ],
  "requestBody": {
    "required": true,
    "description": "Request body",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/GenerateBatchBody"
        }
      }
    }
  },
  "responses": {
    "202": {
      "description": "Batch generation jobs started",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/BatchAsyncResponse"
          },
          "example": {
            "data": {
              "jobs": [
                {
                  "job_id": "fe21477f-7e46-448f-bfdb-96eac80205b8",
                  "item_id": "e8ca0d1b-b445-46f6-862f-26b26ac2c6ff",
                  "item_name": "sitting",
                  "status": "pending",
                  "estimated_cost": 1,
                  "asset_ids": {
                    "image": "25dc5edf-bf41-4a7f-ba23-b783ea2718d8"
                  },
                  "urls": {
                    "transparent_image": "https://assets.masko.ai/fda8417d/cat-api-test-1776591702/sitting-fb7bbd6f.png",
                    "image": "https://assets.masko.ai/fda8417d/cat-api-test-1776591702/sitting-25dc5edf.png"
                  }
                }
              ],
              "total_cost": 2,
              "poll_url": "/api/v1/jobs"
            }
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "402": {
      "description": "Insufficient credits",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    }
  },
  "deprecated": true,
  "operationId": "legacyGenerateBatchCollection"
}

GET/v1/collections/{id}/suggestionsSuggest action poses

Returns AI-generated action/pose suggestions (e.g. "waving", "thinking") tailored to the same resolved parent-plus-child mascot context used by generation. Use these as prompts for POST /v1/collections/{id}/generate. No credit cost.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

variant_idquery

Use this approved mascot variant for suggestions. Omit for Original.

string

Responses

200 Suggested actions

application/json

dataobject · required

Nested fields

suggestionsarray · required

Nested fields

string

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Generate"
  ],
  "summary": "Suggest action poses",
  "description": "Returns AI-generated action/pose suggestions (e.g. \"waving\", \"thinking\") tailored to the same resolved parent-plus-child mascot context used by generation. Use these as prompts for POST `/v1/collections/{id}/generate`. No credit cost.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "schema": {
        "type": "string",
        "format": "uuid",
        "description": "Use this approved mascot variant for suggestions. Omit for Original."
      },
      "required": false,
      "description": "Use this approved mascot variant for suggestions. Omit for Original.",
      "name": "variant_id",
      "in": "query"
    }
  ],
  "responses": {
    "200": {
      "description": "Suggested actions",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SuggestionsResponse"
          },
          "example": {
            "data": {
              "suggestions": [
                "Curious Head Tilt",
                "Wide Eyed Stare",
                "Slow Clay Blink",
                "Gentle Tail Wag",
                "Heavy Paw Waddle",
                "Playful Pounce",
                "Happy Ear Twitch"
              ]
            }
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    }
  },
  "deprecated": true,
  "operationId": "legacyListCollectionSuggestions"
}

GET/v1/collections/{id}/backgrounds/suggestionsSuggest backgrounds for a purpose

Returns five places for what a background is for, from the mascot's world: a preset purpose (splash, onboarding, signup, home, paywall, reward, empty, loading, landing, banner) or your own words. For your own words it also picks the place that fits. Ideas for a preset are saved and returned again until refresh=true. Send one as description, with the same purpose, to POST /v1/collections/{id}/generate with type: "background". No credit cost.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

purposequery

What the background is for: splash, onboarding, signup, home, paywall, reward, empty, loading, landing or banner, or your own words, e.g. "a quiz result page".

string

refreshquery

true writes new ideas for a preset purpose instead of returning the saved ones.

string · true, false

variant_idquery

Approved mascot variant whose world the ideas come from.

string

Responses

200 Five places for the purpose

application/json

dataobject · required

Nested fields

purposestring · required

placestring · required

Values: "phone_screen", "phone_header", "square", "web_hero", "banner"

suggestionsarray · required

Nested fields

titlestring · required

descriptionstring · required

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Generate"
  ],
  "summary": "Suggest backgrounds for a purpose",
  "description": "Returns five places for what a background is for, from the mascot's world: a preset purpose (splash, onboarding, signup, home, paywall, reward, empty, loading, landing, banner) or your own words. For your own words it also picks the place that fits. Ideas for a preset are saved and returned again until refresh=true. Send one as `description`, with the same `purpose`, to POST `/v1/collections/{id}/generate` with `type: \"background\"`. No credit cost.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "schema": {
        "type": "string",
        "minLength": 1,
        "maxLength": 120,
        "default": "splash",
        "description": "What the background is for: splash, onboarding, signup, home, paywall, reward, empty, loading, landing or banner, or your own words, e.g. \"a quiz result page\"."
      },
      "required": false,
      "description": "What the background is for: splash, onboarding, signup, home, paywall, reward, empty, loading, landing or banner, or your own words, e.g. \"a quiz result page\".",
      "name": "purpose",
      "in": "query"
    },
    {
      "schema": {
        "type": "string",
        "enum": [
          "true",
          "false"
        ],
        "description": "true writes new ideas for a preset purpose instead of returning the saved ones."
      },
      "required": false,
      "description": "true writes new ideas for a preset purpose instead of returning the saved ones.",
      "name": "refresh",
      "in": "query"
    },
    {
      "schema": {
        "type": "string",
        "format": "uuid",
        "description": "Approved mascot variant whose world the ideas come from."
      },
      "required": false,
      "description": "Approved mascot variant whose world the ideas come from.",
      "name": "variant_id",
      "in": "query"
    }
  ],
  "responses": {
    "200": {
      "description": "Five places for the purpose",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/BackgroundSuggestionsResponse"
          },
          "example": {
            "data": {
              "purpose": "a quiz result page",
              "place": "phone_screen",
              "suggestions": [
                {
                  "title": "Sunny meadow stage",
                  "description": "A wide meadow under a pale sky, the grass flattening into a clear patch in the middle."
                }
              ]
            }
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    }
  },
  "deprecated": true,
  "operationId": "legacyListCollectionBackgroundSuggestions"
}

PATCH/v1/collections/{id}/settingsUpdate collection settings

Updates mascot export settings. image_exports configures future PNG/WebP derivatives of original, transparent and sticker images; it does not backfill existing images. animation_sizes takes up to 2 smaller widths below 720 px (every animation already gets its 720 px files, so 720 and larger values are ignored) and preserves existing behavior: changed settings may queue exports for existing animations as well as future outputs. Use POST /v1/mascots/{id}/exports for explicit image/video backfill, or the legacy size-variants endpoint for video-only repair. Returns settings_applied, size_variant_jobs and sizes_enabled. No credit cost.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

Request body (required)

Request body

application/json

publish_paramsobject

Export settings. prores_exports enables original-size ProRes 4444 with alpha for future transparent animations. mkpk_exports makes one .mkpk pack (ESP32 Masko SDK) per future forward animation, all with the same width, screen, frames per second, quality and background colour. image_exports applies to future image completions. animation_sizes retains existing automatic video export behavior, including scheduling existing videos when settings change. Use POST /v1/mascots/:id/exports for explicit backfill.

Nested fields

image_exportsobject

Nested fields

enabledboolean · required

sourcesarray · required

Items: 1 to 3

Nested fields

string · original, transparent, sticker

formatsarray · required

Items: 1 to 2

Nested fields

string · png, webp

sizesarray · required

Items: 1 to 5

Nested fields

integer

prores_exportsobject

Automatically create original-delivery-size ProRes 4444 MOV files with alpha after transparent animations finish. Disabled by default.

Nested fields

enabledboolean · required

mkpk_exportsobject

Automatically create one .mkpk pack (ESP32 Masko SDK) per forward animation once its transparent video exists, all with the same width and settings. Disabled by default.

Nested fields

screen_widthinteger

Screen the pack is made for; the frames are centred on it. Set with screen_height. Defaults to the frame size.

Range: 16 to 1024

screen_heightinteger

Range: 16 to 1024

fpsinteger

Frames per second. Defaults to 24.

Range: 1 to 60

qualityinteger

JPEG quality from 1 to 100. Defaults to 75.

Range: 1 to 100

background_colorstring

Colour behind the mascot, as #RRGGBB. Defaults to black.

Pattern: ^#[0-9a-fA-F]{6}$

enabledboolean · required

sizeinteger

Frame width in pixels, a multiple of 16. Required when enabled.

Range: 32 to 1024

animation_sizesobject

Nested fields

enabledboolean · required

Whether animation size variants are generated.

sizesarray · required

Up to 2 smaller pixel widths to generate, from 32 to 719. Every animation already gets its 720 px files, so 720 and larger values are ignored. Common values: 480, 360, 240, 128.

Nested fields

number

force_refreshboolean

Responses

200 Settings updated

application/json

dataobject · required

Nested fields

updatedboolean · required

slugstring

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Settings"
  ],
  "summary": "Update collection settings",
  "description": "Updates mascot export settings. image_exports configures future PNG/WebP derivatives of original, transparent and sticker images; it does not backfill existing images. animation_sizes takes up to 2 smaller widths below 720 px (every animation already gets its 720 px files, so 720 and larger values are ignored) and preserves existing behavior: changed settings may queue exports for existing animations as well as future outputs. Use POST /v1/mascots/{id}/exports for explicit image/video backfill, or the legacy size-variants endpoint for video-only repair. Returns settings_applied, size_variant_jobs and sizes_enabled. No credit cost.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    }
  ],
  "requestBody": {
    "required": true,
    "description": "Request body",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/UpdateSettingsBody"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Settings updated",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/UpdatedFlagResponse"
          },
          "example": {
            "data": {
              "updated": true
            }
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    }
  },
  "deprecated": true,
  "operationId": "legacyUpdateCollectionSettings"
}

POST/v1/collections/{id}/size-variantsBackfill animation size variants

Starts idempotent jobs that make the files each completed animation in this collection lacks: WebM, HEVC, stacked MP4 and stacked AV1, at the animation width and at each of up to 2 smaller sizes, made from its existing background removal. Normal pipeline usage sends {}: it uses the collection configured animation_sizes, or [360] when no sizes are configured, and only makes missing files, so files that exist keep their URLs and animations made before AV1 get their AV1 files. force=true is an explicit admin recovery option that remakes every sized file too; do not use it for normal marketplace/canvas backfills or while relevant jobs are in flight. This endpoint does not regenerate source animations and does not toggle collection settings.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

Idempotency-Keyheader

string

Request body (required)

Request body

application/json

sizesarray

Up to 2 smaller pixel widths to generate. Defaults to the collection's configured animation_sizes, or [360]. Every animation already gets its 720 px files, so 720 and larger values are ignored.

Nested fields

integer

forceboolean

Regenerate even sizes that already exist. Default false (idempotent: only missing sizes, never supersedes in-flight jobs).

Responses

200 Size variant jobs started

application/json

dataobject · required

Nested fields

size_variant_jobsinteger · required

Range: 0 to unbounded

sizesarray · required

Nested fields

integer

forceboolean · required

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Settings"
  ],
  "summary": "Backfill animation size variants",
  "description": "Starts idempotent jobs that make the files each completed animation in this collection lacks: WebM, HEVC, stacked MP4 and stacked AV1, at the animation width and at each of up to 2 smaller sizes, made from its existing background removal. Normal pipeline usage sends `{}`: it uses the collection configured `animation_sizes`, or `[360]` when no sizes are configured, and only makes missing files, so files that exist keep their URLs and animations made before AV1 get their AV1 files. `force=true` is an explicit admin recovery option that remakes every sized file too; do not use it for normal marketplace/canvas backfills or while relevant jobs are in flight. This endpoint does not regenerate source animations and does not toggle collection settings.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.",
      "schema": {
        "type": "string",
        "maxLength": 255
      }
    }
  ],
  "requestBody": {
    "required": true,
    "description": "Request body",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/GenerateSizeVariantsBody"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Size variant jobs started",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SizeVariantsResponse"
          },
          "example": {
            "data": {
              "size_variant_jobs": 3,
              "sizes": [
                360
              ],
              "force": false
            }
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    }
  },
  "deprecated": true,
  "operationId": "legacyCreateCollectionSizeVariant"
}

GET/v1/collections/{id}/canvasesList canvases in a collection

Returns all canvases (state machines / animation graphs) attached to the collection. A canvas describes nodes (poses) and edges (loops or transitions). No credit cost.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

Responses

200 List of canvases

application/json

dataarray · required

Nested fields

idstring · uuid · required

namestring · required

created_atstring · required

updated_atstring · required

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Canvases"
  ],
  "summary": "List canvases in a collection",
  "description": "Returns all canvases (state machines / animation graphs) attached to the collection. A canvas describes nodes (poses) and edges (loops or transitions). No credit cost.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    }
  ],
  "responses": {
    "200": {
      "description": "List of canvases",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CanvasListResponse"
          },
          "example": {
            "data": []
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    }
  },
  "deprecated": true,
  "operationId": "legacyListCollectionCanvases"
}

POST/v1/collections/{id}/canvasesCreate a canvas

Creates a canvas for the collection. If template_id is provided, items and images are generated for every node (image cost per node, 1 credit each). With no template_id, creates an empty canvas with zero cost. Returns 201.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

Idempotency-Keyheader

string

Request body (required)

Request body

application/json

namestring · required

Display name for the canvas.

Length: 1 to unbounded characters

graphobject

Canvas graph JSON with nodes, edges, and inputs. Omit to create an empty canvas. Mutually exclusive with template_id.

template_idstring

Optional template to apply at creation. Creates items, starts image generation for each node, and returns the populated graph plus job IDs. List templates via GET /v1/canvas-templates.

Length: 1 to unbounded characters

node_overridesobject

Per-node overrides keyed by node key. Merged into template nodes before creation. Only used when template_id is provided.

edge_overridesobject

Per-edge overrides keyed by "source->target" key. Merged into template edges before creation. Only used when template_id is provided.

Responses

201 Created canvas (populated if template_id provided)

application/json

dataobject · required

Nested fields

objectstring

Resource type. Always "canvas".

Values: "canvas"

idstring · uuid · required

namestring · required

graphobject · required

graph_content_hashstring · required

Revision token for the full authored graph. Send this as expected_graph_hash when replacing the graph.

statusobject

Nested fields

nodesobject · required

Nested fields

totalnumber · required

completednumber · required

pendingnumber · required

Incomplete node count. Includes failed nodes for backward compatibility; inspect failed for the terminal subset.

failednumber · required

edgesobject · required

Nested fields

totalnumber · required

completednumber · required

pendingnumber · required

failednumber · required

readyboolean · required

generated_readyboolean

preview_readyboolean

mediaobject

Nested fields

generationobject · required

Nested fields

readyboolean · required

nodesobject · required

Nested fields

totalnumber · required

completednumber · required

pendingnumber · required

Incomplete node count. Includes failed nodes for backward compatibility; inspect failed for the terminal subset.

failednumber · required

edgesobject · required

Nested fields

totalnumber · required

completednumber · required

pendingnumber · required

failednumber · required

previewobject · required

Nested fields

readyboolean · required

repairableboolean · required

repairable_edgesnumber · required

waiting_edgesnumber · required

missing_edgesnumber · required

missing_formatsarray · required

Nested fields

string · webm, hevc

variantsobject · required

Nested fields

sizesarray · required

Nested fields

string

missingarray · required

Nested fields

edge_idstring · required

sizestring · required

formatsarray · required

Nested fields

See the OpenAPI schema for deeper nested fields.

failed_nodesarray · required

Nested fields

node_idstring · required

job_idstring · uuid · nullable · required

errorstring · required

failed_edgesarray · required

Nested fields

edge_idstring · required

job_idstring · uuid · nullable · required

errorstring · required

edge_mediaarray

Nested fields

edge_idstring · required

sourcestring · required

targetstring · required

video_asset_idstring · uuid · nullable · required

baseobject · required

Nested fields

video_readyboolean · required

webm_readyboolean · required

hevc_readyboolean · required

preview_readyboolean · required

derivatives_in_flightboolean · required

source_job_idstring · uuid

source_job_statusstring

missingarray · required

Nested fields

string · webm, hevc

variantsobject · required

created_atstring

updated_atstring

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Canvases"
  ],
  "summary": "Create a canvas",
  "description": "Creates a canvas for the collection. If `template_id` is provided, items and images are generated for every node (image cost per node, 1 credit each). With no `template_id`, creates an empty canvas with zero cost. Returns 201.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.",
      "schema": {
        "type": "string",
        "maxLength": 255
      }
    }
  ],
  "requestBody": {
    "required": true,
    "description": "Request body",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/CreateCanvasBody"
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Created canvas (populated if template_id provided)",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CanvasResponse"
          },
          "example": {
            "data": {
              "id": "8c4b872c-df43-4d64-b84c-00f0d8314140",
              "name": "test-empty-canvas",
              "graph": {
                "edges": [],
                "nodes": [],
                "inputs": [],
                "viewport": {
                  "x": 0,
                  "y": 0,
                  "zoom": 1
                }
              },
              "created_at": "2026-04-19T09:42:15.222526+00:00"
            }
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    }
  },
  "deprecated": true,
  "operationId": "legacyCreateCollectionCanvas"
}

GET/v1/collections/{id}/canvases/{canvasId}Get canvas details

Returns the canvas with its full graph (nodes, edges, inputs, viewport) and media status. For agents: use status.media as the canonical readiness interface. status.media.generation.ready means node images and parent edge videos exist. Inspect status.failed_nodes and status.failed_edges for terminal generation failures and customer-safe error messages before deciding whether to start a new paid attempt. status.nodes.pending remains the backward-compatible count of all incomplete nodes, including failed nodes; status.nodes.failed identifies the terminal subset. status.media.preview.ready means the canvas editor can play every concrete edge using completed base WebM and HEVC derivatives. If status.media.preview.waiting_edges > 0, wait and poll again because the original generation job is still preparing derivatives. If status.media.preview.repairable=true, call POST /v1/collections/{id}/canvases/{canvasId}/repair with dry_run=true before repairing. status.media.variants reports optimized size-variant facts only; base preview repair does not create variants. status.ready, status.generated_ready, and status.preview_ready remain as backward-compatible aliases.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

canvasIdpath · required

string

Responses

200 Canvas details with status

application/json

dataobject · required

Nested fields

objectstring

Resource type. Always "canvas".

Values: "canvas"

idstring · uuid · required

namestring · required

graphobject · required

graph_content_hashstring · required

Revision token for the full authored graph. Send this as expected_graph_hash when replacing the graph.

statusobject

Nested fields

nodesobject · required

Nested fields

totalnumber · required

completednumber · required

pendingnumber · required

Incomplete node count. Includes failed nodes for backward compatibility; inspect failed for the terminal subset.

failednumber · required

edgesobject · required

Nested fields

totalnumber · required

completednumber · required

pendingnumber · required

failednumber · required

readyboolean · required

generated_readyboolean

preview_readyboolean

mediaobject

Nested fields

generationobject · required

Nested fields

readyboolean · required

nodesobject · required

Nested fields

totalnumber · required

completednumber · required

pendingnumber · required

Incomplete node count. Includes failed nodes for backward compatibility; inspect failed for the terminal subset.

failednumber · required

edgesobject · required

Nested fields

totalnumber · required

completednumber · required

pendingnumber · required

failednumber · required

previewobject · required

Nested fields

readyboolean · required

repairableboolean · required

repairable_edgesnumber · required

waiting_edgesnumber · required

missing_edgesnumber · required

missing_formatsarray · required

Nested fields

string · webm, hevc

variantsobject · required

Nested fields

sizesarray · required

Nested fields

string

missingarray · required

Nested fields

edge_idstring · required

sizestring · required

formatsarray · required

Nested fields

See the OpenAPI schema for deeper nested fields.

failed_nodesarray · required

Nested fields

node_idstring · required

job_idstring · uuid · nullable · required

errorstring · required

failed_edgesarray · required

Nested fields

edge_idstring · required

job_idstring · uuid · nullable · required

errorstring · required

edge_mediaarray

Nested fields

edge_idstring · required

sourcestring · required

targetstring · required

video_asset_idstring · uuid · nullable · required

baseobject · required

Nested fields

video_readyboolean · required

webm_readyboolean · required

hevc_readyboolean · required

preview_readyboolean · required

derivatives_in_flightboolean · required

source_job_idstring · uuid

source_job_statusstring

missingarray · required

Nested fields

string · webm, hevc

variantsobject · required

created_atstring

updated_atstring

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Canvases"
  ],
  "summary": "Get canvas details",
  "description": "Returns the canvas with its full graph (nodes, edges, inputs, viewport) and media status. For agents: use `status.media` as the canonical readiness interface. `status.media.generation.ready` means node images and parent edge videos exist. Inspect `status.failed_nodes` and `status.failed_edges` for terminal generation failures and customer-safe error messages before deciding whether to start a new paid attempt. `status.nodes.pending` remains the backward-compatible count of all incomplete nodes, including failed nodes; `status.nodes.failed` identifies the terminal subset. `status.media.preview.ready` means the canvas editor can play every concrete edge using completed base WebM and HEVC derivatives. If `status.media.preview.waiting_edges > 0`, wait and poll again because the original generation job is still preparing derivatives. If `status.media.preview.repairable=true`, call POST `/v1/collections/{id}/canvases/{canvasId}/repair` with `dry_run=true` before repairing. `status.media.variants` reports optimized size-variant facts only; base preview repair does not create variants. `status.ready`, `status.generated_ready`, and `status.preview_ready` remain as backward-compatible aliases.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "canvasId",
      "in": "path"
    }
  ],
  "responses": {
    "200": {
      "description": "Canvas details with status",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CanvasResponse"
          },
          "example": {
            "data": {
              "id": "280ceab9-4673-4c78-b37c-3617feb51914",
              "name": "test-canvas-from-template",
              "graph": {
                "edges": [
                  {
                    "id": "d7420e54-9545-4527-bff0-912be67c3758",
                    "jobId": "a3c6ec30-a82c-41b2-a28f-37bedf369815",
                    "source": "38df9602-c21a-4637-9cea-c0962433d2e1",
                    "target": "38df9602-c21a-4637-9cea-c0962433d2e1",
                    "reverse": false,
                    "duration": 4,
                    "conditions": [],
                    "description": "Gentle breathing, slow blinking, tail curling slightly",
                    "videoAssetId": "a98ba960-c1b3-4bf5-9e6f-1d57b43c651d",
                    "reverseOfEdgeId": null
                  }
                ],
                "nodes": [
                  {
                    "x": 0,
                    "y": 0,
                    "id": "38df9602-c21a-4637-9cea-c0962433d2e1",
                    "itemName": "Idle"
                  }
                ],
                "inputs": [],
                "viewport": {
                  "x": 0,
                  "y": 0,
                  "zoom": 0.8
                }
              },
              "status": {
                "nodes": {
                  "total": 2,
                  "completed": 2,
                  "pending": 0,
                  "failed": 0
                },
                "edges": {
                  "total": 3,
                  "completed": 3,
                  "pending": 0,
                  "failed": 0
                },
                "ready": true,
                "generated_ready": true,
                "preview_ready": true,
                "media": {
                  "generation": {
                    "ready": true,
                    "nodes": {
                      "total": 2,
                      "completed": 2,
                      "pending": 0,
                      "failed": 0
                    },
                    "edges": {
                      "total": 3,
                      "completed": 3,
                      "pending": 0,
                      "failed": 0
                    }
                  },
                  "preview": {
                    "ready": true,
                    "repairable": false,
                    "repairable_edges": 0,
                    "waiting_edges": 0,
                    "missing_edges": 0,
                    "missing_formats": []
                  },
                  "variants": {
                    "sizes": [],
                    "missing": []
                  }
                },
                "failed_nodes": [],
                "failed_edges": [],
                "edge_media": [
                  {
                    "edge_id": "d7420e54-9545-4527-bff0-912be67c3758",
                    "source": "38df9602-c21a-4637-9cea-c0962433d2e1",
                    "target": "38df9602-c21a-4637-9cea-c0962433d2e1",
                    "video_asset_id": "a98ba960-c1b3-4bf5-9e6f-1d57b43c651d",
                    "base": {
                      "video_ready": true,
                      "webm_ready": true,
                      "hevc_ready": true,
                      "preview_ready": true,
                      "derivatives_in_flight": false,
                      "missing": []
                    },
                    "variants": {}
                  }
                ]
              }
            }
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    }
  },
  "deprecated": true,
  "operationId": "legacyGetCollectionCanvas"
}

PATCH/v1/collections/{id}/canvases/{canvasId}Replace a complete canvas graph

Replaces the complete authored graph. Read the canvas first and send its graph_content_hash as expected_graph_hash. If another editor changes the graph first, the write returns 409 instead of overwriting it. Generated asset fields on unchanged nodes and edges are preserved. No credit cost; generation is triggered separately.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

canvasIdpath · required

string

Request body (required)

Request body

application/json

graphobject · required

Full canvas graph to replace the current one. Nodes, edges, and inputs are overwritten.

expected_graph_hashstring

Graph content hash returned by the latest GET. When provided, the update is rejected with 409 if the canvas changed before this full-graph save.

Length: 1 to unbounded characters

Responses

200 Canvas updated

application/json

dataobject · required

Nested fields

objectstring

Resource type. Always "canvas".

Values: "canvas"

idstring · uuid · required

namestring · required

graphobject · required

graph_content_hashstring · required

Revision token for the full authored graph. Send this as expected_graph_hash when replacing the graph.

statusobject

Nested fields

nodesobject · required

Nested fields

totalnumber · required

completednumber · required

pendingnumber · required

Incomplete node count. Includes failed nodes for backward compatibility; inspect failed for the terminal subset.

failednumber · required

edgesobject · required

Nested fields

totalnumber · required

completednumber · required

pendingnumber · required

failednumber · required

readyboolean · required

generated_readyboolean

preview_readyboolean

mediaobject

Nested fields

generationobject · required

Nested fields

readyboolean · required

nodesobject · required

Nested fields

totalnumber · required

completednumber · required

pendingnumber · required

Incomplete node count. Includes failed nodes for backward compatibility; inspect failed for the terminal subset.

failednumber · required

edgesobject · required

Nested fields

totalnumber · required

completednumber · required

pendingnumber · required

failednumber · required

previewobject · required

Nested fields

readyboolean · required

repairableboolean · required

repairable_edgesnumber · required

waiting_edgesnumber · required

missing_edgesnumber · required

missing_formatsarray · required

Nested fields

string · webm, hevc

variantsobject · required

Nested fields

sizesarray · required

Nested fields

string

missingarray · required

Nested fields

edge_idstring · required

sizestring · required

formatsarray · required

Nested fields

See the OpenAPI schema for deeper nested fields.

failed_nodesarray · required

Nested fields

node_idstring · required

job_idstring · uuid · nullable · required

errorstring · required

failed_edgesarray · required

Nested fields

edge_idstring · required

job_idstring · uuid · nullable · required

errorstring · required

edge_mediaarray

Nested fields

edge_idstring · required

sourcestring · required

targetstring · required

video_asset_idstring · uuid · nullable · required

baseobject · required

Nested fields

video_readyboolean · required

webm_readyboolean · required

hevc_readyboolean · required

preview_readyboolean · required

derivatives_in_flightboolean · required

source_job_idstring · uuid

source_job_statusstring

missingarray · required

Nested fields

string · webm, hevc

variantsobject · required

created_atstring

updated_atstring

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Canvases"
  ],
  "summary": "Replace a complete canvas graph",
  "description": "Replaces the complete authored graph. Read the canvas first and send its graph_content_hash as expected_graph_hash. If another editor changes the graph first, the write returns 409 instead of overwriting it. Generated asset fields on unchanged nodes and edges are preserved. No credit cost; generation is triggered separately.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "canvasId",
      "in": "path"
    }
  ],
  "requestBody": {
    "required": true,
    "description": "Request body",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/UpdateCanvasBody"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Canvas updated",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CanvasResponse"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    }
  },
  "deprecated": true,
  "operationId": "legacyUpdateCollectionCanvas"
}

DELETE/v1/collections/{id}/canvases/{canvasId}Delete a canvas

Deletes a canvas without saved history. Generated node/edge assets are kept. Returns 204, or 409 when checkpoints or releases retain the canvas. No credit cost.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

canvasIdpath · required

string

Responses

204 Canvas deleted

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Canvases"
  ],
  "summary": "Delete a canvas",
  "description": "Deletes a canvas without saved history. Generated node/edge assets are kept. Returns 204, or 409 when checkpoints or releases retain the canvas. No credit cost.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "canvasId",
      "in": "path"
    }
  ],
  "responses": {
    "204": {
      "description": "Canvas deleted",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    }
  },
  "deprecated": true,
  "operationId": "legacyDeleteCollectionCanvas"
}

POST/v1/collections/{id}/canvases/{canvasId}/repairRepair canvas preview media

Plans or starts a narrow repair for missing base WebM/HEVC derivatives on videos already assigned to this canvas. Agent workflow: first call with dry_run=true or omit dry_run because it defaults to true. Read status.media.preview, summary, repairs, in_flight, and skipped. If status.media.preview.waiting_edges > 0, wait and poll again instead of repairing. Only call again with dry_run=false if the repair plan matches the intended canvas videos. This endpoint is for the specific case where status.media.generation.ready=true, status.media.preview.ready=false, and status.media.preview.repairable=true. It does not regenerate animations, does not run collection-wide jobs, does not create size variants, does not expose prompt/model controls, does not force regeneration, and does not archive existing assets.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

canvasIdpath · required

string

Idempotency-Keyheader

string

Request body (required)

Request body

application/json

targetstring

Repair target. Use video_derivatives when canvas status shows status.media.preview.repairable=true because completed edge videos are missing base WebM and/or HEVC child assets. If status.media.preview.waiting_edges > 0, wait and poll again instead of repairing. This target only repairs videos already assigned to the canvas graph.

Values: "video_derivatives"

Default: "video_derivatives"

formatsarray

Base derivative formats to repair. Defaults to both webm and hevc. This does not include size variants; optimized sizes must be generated through the size-variant flow.

Default: ["webm","hevc"]

Items: 1 to unbounded

Nested fields

string · webm, hevc

dry_runboolean

When true, returns the exact repair plan without creating jobs or assets. Defaults to true. Agents should call dry_run=true first, inspect repairs/skipped/in_flight, then call dry_run=false only if the plan touches the intended videos.

Default: true

Responses

200 Repair plan returned

application/json

dataobject · required

Nested fields

targetstring · required

Values: "video_derivatives"

dry_runboolean · required

formatsarray · required

Nested fields

string · webm, hevc

statusobject · required

Nested fields

generated_readyboolean · required

preview_readyboolean · required

mediaobject

Nested fields

generationobject · required

Nested fields

readyboolean · required

nodesobject · required

Nested fields

totalnumber · required

completednumber · required

pendingnumber · required

Incomplete node count. Includes failed nodes for backward compatibility; inspect failed for the terminal subset.

failednumber · required

edgesobject · required

Nested fields

totalnumber · required

completednumber · required

pendingnumber · required

failednumber · required

previewobject · required

Nested fields

readyboolean · required

repairableboolean · required

repairable_edgesnumber · required

waiting_edgesnumber · required

missing_edgesnumber · required

missing_formatsarray · required

Nested fields

string · webm, hevc

variantsobject · required

Nested fields

sizesarray · required

Nested fields

string

missingarray · required

Nested fields

edge_idstring · required

sizestring · required

formatsarray · required

Nested fields

See the OpenAPI schema for deeper nested fields.

summaryobject · required

Nested fields

edges_checkednumber · required

videos_checkednumber · required

videos_readynumber · required

videos_to_repairnumber · required

videos_in_flightnumber · required

videos_skippednumber · required

repairsarray · required

Nested fields

video_asset_idstring · uuid · required

edge_idsarray · required

Nested fields

string

missingarray · required

Nested fields

string · webm, hevc

actionstring · required

Values: "create_derivatives", "already_in_flight"

job_idstring · uuid

in_flightarray · required

Nested fields

video_asset_idstring · uuid · required

edge_idsarray · required

Nested fields

string

missingarray · required

Nested fields

string · webm, hevc

actionstring · required

Values: "create_derivatives", "already_in_flight"

job_idstring · uuid

skippedarray · required

Nested fields

video_asset_idstring · uuid · required

edge_idsarray · required

Nested fields

string

reasonstring · required

jobsarray

Nested fields

job_idstring · uuid · required

poll_urlstring · required

video_asset_idstring · uuid · required

edge_idsarray · required

Nested fields

string

formatsarray · required

Nested fields

string · webm, hevc

202 Repair jobs started

application/json

dataobject · required

Nested fields

targetstring · required

Values: "video_derivatives"

dry_runboolean · required

formatsarray · required

Nested fields

string · webm, hevc

statusobject · required

Nested fields

generated_readyboolean · required

preview_readyboolean · required

mediaobject

Nested fields

generationobject · required

Nested fields

readyboolean · required

nodesobject · required

Nested fields

totalnumber · required

completednumber · required

pendingnumber · required

Incomplete node count. Includes failed nodes for backward compatibility; inspect failed for the terminal subset.

failednumber · required

edgesobject · required

Nested fields

totalnumber · required

completednumber · required

pendingnumber · required

failednumber · required

previewobject · required

Nested fields

readyboolean · required

repairableboolean · required

repairable_edgesnumber · required

waiting_edgesnumber · required

missing_edgesnumber · required

missing_formatsarray · required

Nested fields

string · webm, hevc

variantsobject · required

Nested fields

sizesarray · required

Nested fields

string

missingarray · required

Nested fields

edge_idstring · required

sizestring · required

formatsarray · required

Nested fields

See the OpenAPI schema for deeper nested fields.

summaryobject · required

Nested fields

edges_checkednumber · required

videos_checkednumber · required

videos_readynumber · required

videos_to_repairnumber · required

videos_in_flightnumber · required

videos_skippednumber · required

repairsarray · required

Nested fields

video_asset_idstring · uuid · required

edge_idsarray · required

Nested fields

string

missingarray · required

Nested fields

string · webm, hevc

actionstring · required

Values: "create_derivatives", "already_in_flight"

job_idstring · uuid

in_flightarray · required

Nested fields

video_asset_idstring · uuid · required

edge_idsarray · required

Nested fields

string

missingarray · required

Nested fields

string · webm, hevc

actionstring · required

Values: "create_derivatives", "already_in_flight"

job_idstring · uuid

skippedarray · required

Nested fields

video_asset_idstring · uuid · required

edge_idsarray · required

Nested fields

string

reasonstring · required

jobsarray

Nested fields

job_idstring · uuid · required

poll_urlstring · required

video_asset_idstring · uuid · required

edge_idsarray · required

Nested fields

string

formatsarray · required

Nested fields

string · webm, hevc

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Canvases"
  ],
  "summary": "Repair canvas preview media",
  "description": "Plans or starts a narrow repair for missing base WebM/HEVC derivatives on videos already assigned to this canvas. Agent workflow: first call with `dry_run=true` or omit `dry_run` because it defaults to true. Read `status.media.preview`, `summary`, `repairs`, `in_flight`, and `skipped`. If `status.media.preview.waiting_edges > 0`, wait and poll again instead of repairing. Only call again with `dry_run=false` if the repair plan matches the intended canvas videos. This endpoint is for the specific case where `status.media.generation.ready=true`, `status.media.preview.ready=false`, and `status.media.preview.repairable=true`. It does not regenerate animations, does not run collection-wide jobs, does not create size variants, does not expose prompt/model controls, does not force regeneration, and does not archive existing assets.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "canvasId",
      "in": "path"
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.",
      "schema": {
        "type": "string",
        "maxLength": 255
      }
    }
  ],
  "requestBody": {
    "required": true,
    "description": "Request body",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/RepairCanvasBody"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Repair plan returned",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CanvasRepairResponse"
          },
          "example": {
            "data": {
              "target": "video_derivatives",
              "dry_run": true,
              "formats": [
                "webm",
                "hevc"
              ],
              "status": {
                "generated_ready": true,
                "preview_ready": false,
                "media": {
                  "generation": {
                    "ready": true,
                    "nodes": {
                      "total": 6,
                      "completed": 6,
                      "pending": 0,
                      "failed": 0
                    },
                    "edges": {
                      "total": 42,
                      "completed": 42,
                      "pending": 0,
                      "failed": 0
                    }
                  },
                  "preview": {
                    "ready": false,
                    "repairable": true,
                    "repairable_edges": 2,
                    "waiting_edges": 0,
                    "missing_edges": 2,
                    "missing_formats": [
                      "webm",
                      "hevc"
                    ]
                  },
                  "variants": {
                    "sizes": [
                      "360"
                    ],
                    "missing": []
                  }
                }
              },
              "summary": {
                "edges_checked": 42,
                "videos_checked": 38,
                "videos_ready": 36,
                "videos_to_repair": 2,
                "videos_in_flight": 0,
                "videos_skipped": 0
              },
              "repairs": [
                {
                  "video_asset_id": "a98ba960-c1b3-4bf5-9e6f-1d57b43c651d",
                  "edge_ids": [
                    "enter-hover-perk"
                  ],
                  "missing": [
                    "webm",
                    "hevc"
                  ],
                  "action": "create_derivatives"
                }
              ],
              "in_flight": [],
              "skipped": []
            }
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "202": {
      "description": "Repair jobs started",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CanvasRepairResponse"
          },
          "example": {
            "data": {
              "target": "video_derivatives",
              "dry_run": false,
              "formats": [
                "webm",
                "hevc"
              ],
              "status": {
                "generated_ready": true,
                "preview_ready": false,
                "media": {
                  "generation": {
                    "ready": true,
                    "nodes": {
                      "total": 6,
                      "completed": 6,
                      "pending": 0,
                      "failed": 0
                    },
                    "edges": {
                      "total": 42,
                      "completed": 42,
                      "pending": 0,
                      "failed": 0
                    }
                  },
                  "preview": {
                    "ready": false,
                    "repairable": true,
                    "repairable_edges": 2,
                    "waiting_edges": 0,
                    "missing_edges": 2,
                    "missing_formats": [
                      "webm",
                      "hevc"
                    ]
                  },
                  "variants": {
                    "sizes": [
                      "360"
                    ],
                    "missing": []
                  }
                }
              },
              "summary": {
                "edges_checked": 42,
                "videos_checked": 38,
                "videos_ready": 36,
                "videos_to_repair": 2,
                "videos_in_flight": 0,
                "videos_skipped": 0
              },
              "repairs": [
                {
                  "video_asset_id": "a98ba960-c1b3-4bf5-9e6f-1d57b43c651d",
                  "edge_ids": [
                    "enter-hover-perk"
                  ],
                  "missing": [
                    "webm",
                    "hevc"
                  ],
                  "action": "create_derivatives"
                }
              ],
              "in_flight": [],
              "skipped": [],
              "jobs": [
                {
                  "job_id": "a1b2c3d4-0000-0000-0000-000000000001",
                  "poll_url": "/v1/jobs/a1b2c3d4-0000-0000-0000-000000000001",
                  "video_asset_id": "a98ba960-c1b3-4bf5-9e6f-1d57b43c651d",
                  "edge_ids": [
                    "enter-hover-perk"
                  ],
                  "formats": [
                    "webm",
                    "hevc"
                  ]
                }
              ]
            }
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    }
  },
  "deprecated": true,
  "operationId": "legacyRepairCollectionCanvas"
}

POST/v1/collections/{id}/canvases/{canvasId}/presentation/detect-facingDetect canvas natural facing

Analyzes completed canvas node images and returns a suggested presentation.naturalFacing value plus node-level evidence. This is a synchronous analysis endpoint. It does not write to the canvas graph and has no credit cost.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

canvasIdpath · required

string

Idempotency-Keyheader

string

Responses

200 Suggested natural-facing presentation value

application/json

dataobject · required

Nested fields

suggestedNaturalFacingstring · required

Values: "left", "neutral", "right"

confidencenumber · required

warningstring

analyzedNodeCountinteger · required

Range: 0 to unbounded

nodeResultsarray · required

Nested fields

nodeIdstring · required

nodeNamestring · required

facingstring · required

Values: "left", "neutral", "right"

confidencenumber · required

reasonstring

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Canvases"
  ],
  "summary": "Detect canvas natural facing",
  "description": "Analyzes completed canvas node images and returns a suggested presentation.naturalFacing value plus node-level evidence. This is a synchronous analysis endpoint. It does not write to the canvas graph and has no credit cost.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "canvasId",
      "in": "path"
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.",
      "schema": {
        "type": "string",
        "maxLength": 255
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Suggested natural-facing presentation value",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CanvasFacingDetectionResponse"
          },
          "example": {
            "data": {
              "suggestedNaturalFacing": "left",
              "confidence": 0.82,
              "analyzedNodeCount": 3,
              "nodeResults": [
                {
                  "nodeId": "idle",
                  "nodeName": "Idle",
                  "facing": "left",
                  "confidence": 0.88,
                  "reason": "The mascot has a consistent left-facing body angle."
                }
              ]
            }
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    }
  },
  "deprecated": true,
  "operationId": "legacyDetectFacingCollectionCanvasPresentation"
}

POST/v1/collections/{id}/canvases/{canvasId}/graph/extendLegacy partial canvas graph extension

Deprecated compatibility endpoint. New authoring clients should read the complete graph and graph_content_hash, reconcile locally, and PATCH the complete graph with expected_graph_hash.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

canvasIdpath · required

string

Idempotency-Keyheader

string

Request body (required)

Request body

application/json

add_nodesarray

Nodes to append. Fails if any node ID already exists.

Default: []

Nested fields

idstring · required

Length: 1 to unbounded characters

generationVariantIdstring · uuid

Approved variant in the same collection used by generate-all for a new pose. Existing pose identity is preserved; completed assets are not regenerated.

add_edgesarray

Edges to append. Fails if any edge ID already exists.

Default: []

Nested fields

idstring · required

Length: 1 to unbounded characters

update_edgesarray

Partial edge patches keyed by id. Existing edge fields are preserved unless explicitly overwritten.

Default: []

Nested fields

idstring · required

Length: 1 to unbounded characters

add_inputsarray

Inputs to append. Existing input names are left unchanged.

Default: []

Nested fields

namestring · required

Length: 1 to unbounded characters

Responses

200 Canvas graph extended

application/json

dataobject · required

Nested fields

idstring · uuid · required

namestring · required

graphobject · required

updated_atstring · required

addedobject · required

Nested fields

nodesnumber · required

edgesnumber · required

inputsnumber · required

updatedobject · required

Nested fields

edgesnumber · required

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Canvases"
  ],
  "summary": "Legacy partial canvas graph extension",
  "deprecated": true,
  "description": "Deprecated compatibility endpoint. New authoring clients should read the complete graph and graph_content_hash, reconcile locally, and PATCH the complete graph with expected_graph_hash.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "canvasId",
      "in": "path"
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.",
      "schema": {
        "type": "string",
        "maxLength": 255
      }
    }
  ],
  "requestBody": {
    "required": true,
    "description": "Request body",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ExtendCanvasGraphBody"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Canvas graph extended",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CanvasGraphExtendResponse"
          },
          "example": {
            "data": {
              "id": "280ceab9-4673-4c78-b37c-3617feb51914",
              "name": "Main canvas",
              "graph": {
                "nodes": [],
                "edges": [],
                "inputs": [],
                "viewport": {
                  "x": 0,
                  "y": 0,
                  "zoom": 1
                }
              },
              "updated_at": "2026-05-04T12:00:00.000Z",
              "added": {
                "nodes": 1,
                "edges": 2,
                "inputs": 1
              },
              "updated": {
                "edges": 1
              }
            }
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    }
  },
  "operationId": "legacyExtendCollectionCanvasGraph"
}

PATCH/v1/collections/{id}/canvases/{canvasId}/edges/{edgeId}Patch a canvas edge

Patches one edge without replacing the graph. Use this for speed tuning after generation: normal transitions use speed 2, snappy interact transitions use 3-4, held/special loops use 2, and calm loops use 1. speedInput ties the clip speed to a number input declared in graph.inputs, which the app sets at runtime (speed times that value, kept between 0.2 and 4); the next release carries it to the Masko players.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

canvasIdpath · required

string

edgeIdpath · required

string

Request body (required)

Request body

application/json

speednumber

Playback speed multiplier for this edge. Normal transitions use 2, snappy interact transitions use 3-4, calm loops use 1.

Range: 0.1 to 10

speedInputstring · nullable

A number input declared in graph.inputs that this clip speed follows: it plays at speed times the value the app sets, kept between 0.2 and 4. null stops following one.

Length: 1 to unbounded characters

Responses

200 Canvas edge patched

application/json

dataobject · required

Nested fields

idstring · uuid · required

namestring · required

edgeobject · required

graphobject · required

updated_atstring · required

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Canvases"
  ],
  "summary": "Patch a canvas edge",
  "description": "Patches one edge without replacing the graph. Use this for speed tuning after generation: normal transitions use speed 2, snappy interact transitions use 3-4, held/special loops use 2, and calm loops use 1. speedInput ties the clip speed to a number input declared in graph.inputs, which the app sets at runtime (speed times that value, kept between 0.2 and 4); the next release carries it to the Masko players.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "canvasId",
      "in": "path"
    },
    {
      "schema": {
        "type": "string"
      },
      "required": true,
      "name": "edgeId",
      "in": "path"
    }
  ],
  "requestBody": {
    "required": true,
    "description": "Request body",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/PatchCanvasEdgeBody"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Canvas edge patched",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CanvasEdgePatchResponse"
          },
          "example": {
            "data": {
              "id": "280ceab9-4673-4c78-b37c-3617feb51914",
              "name": "Main canvas",
              "edge": {
                "id": "idle-to-interact",
                "source": "idle",
                "target": "interact",
                "duration": 4,
                "speed": 3
              },
              "graph": {
                "nodes": [],
                "edges": [],
                "inputs": [],
                "viewport": {
                  "x": 0,
                  "y": 0,
                  "zoom": 1
                }
              },
              "updated_at": "2026-05-04T12:00:00.000Z"
            }
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    }
  },
  "deprecated": true,
  "operationId": "legacyUpdateCollectionCanvasEdge"
}

POST/v1/collections/{id}/canvases/{canvasId}/edges/{edgeId}/generateGenerate a single canvas edge

Dispatches generation for one specific canvas edge by ID. Costs the same as a single edge in generate-all: duration * 2 for animation_model=standard or duration * 6 for premium. Without animation_model, legacy duration * 5 pricing is retained. If the edge already has a video asset, archives the old assets and re-dispatches. Any State edges (source: "*") and reverse edges are rejected with 400. Requires the source and target nodes to already have generated images. Loops use the source pose receipt, even on a mixed-variant canvas. Transitions retain both endpoint contexts. For uploads without receipts, the canvas context selects matching references; ambiguous shared uploads return 409 before charging.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

canvasIdpath · required

string

edgeIdpath · required

string

Idempotency-Keyheader

string

Request body (required)

Request body

application/json

animation_modelstring

Same choices as Studio: standard costs 2 credits/sec (2–15s); premium costs 6 credits/sec (4–30s). Both default to 5s. Omit to preserve legacy generation at 5 credits/sec (4–10s, default 4s).

Values: "standard", "premium"

durationinteger

Range: 2 to 30

Responses

202 Edge generation started

application/json

dataobject · required

Nested fields

job_idstring · uuid · required

edge_idstring · required

typestring · required

Values: "loop", "transition"

sourcestring · required

targetstring · required

costnumber · required

urlsobject

poll_urlstring · required

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Canvases"
  ],
  "summary": "Generate a single canvas edge",
  "description": "Dispatches generation for one specific canvas edge by ID. Costs the same as a single edge in generate-all: duration * 2 for animation_model=standard or duration * 6 for premium. Without animation_model, legacy duration * 5 pricing is retained. If the edge already has a video asset, archives the old assets and re-dispatches. Any State edges (source: \"*\") and reverse edges are rejected with 400. Requires the source and target nodes to already have generated images. Loops use the source pose receipt, even on a mixed-variant canvas. Transitions retain both endpoint contexts. For uploads without receipts, the canvas context selects matching references; ambiguous shared uploads return 409 before charging.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "canvasId",
      "in": "path"
    },
    {
      "schema": {
        "type": "string"
      },
      "required": true,
      "name": "edgeId",
      "in": "path"
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.",
      "schema": {
        "type": "string",
        "maxLength": 255
      }
    }
  ],
  "requestBody": {
    "required": true,
    "description": "Request body",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/GenerateEdgeBody"
        }
      }
    }
  },
  "responses": {
    "202": {
      "description": "Edge generation started",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CanvasEdgeGenerateResponse"
          },
          "example": {
            "data": {
              "job_id": "a1b2c3d4-0000-0000-0000-000000000001",
              "edge_id": "idle-to-interact",
              "type": "transition",
              "source": "Idle",
              "target": "Interact",
              "cost": 20,
              "urls": {},
              "poll_url": "/v1/jobs/a1b2c3d4-0000-0000-0000-000000000001"
            }
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    }
  },
  "deprecated": true,
  "operationId": "legacyGenerateCollectionCanvasEdge"
}

POST/v1/collections/{id}/canvases/{canvasId}/edges/{edgeId}/refine-maskRefine a canvas edge video mask

Convenience wrapper around POST /v1/assets/{id}/refine-mask for a canvas edge. The route resolves the edge videoAssetId, refines that video asset mask, and re-exports the active derived formats/sizes. The canvas graph keeps the same raw video asset; desktop playback updates because the active linked WebM/HEVC/stacked variants are replaced underneath it. Any State and reverse edges are rejected because they do not own an independent video asset.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

canvasIdpath · required

string

edgeIdpath · required

string

Idempotency-Keyheader

string

Request body (required)

Request body

application/json

opstring

Mask operation. add unions the prompted subject into the active mask; subtract removes it from the active mask.

Values: "add", "subtract"

Default: "add"

promptstring · required

Text prompt for the mask region to refine, e.g. "the soccer ball".

Length: 1 to unbounded characters

modelstring

Background mask refinement quality. Defaults to pro.

Values: "original", "pro"

Default: "pro"

edge_cleanupobject

Optional edge cleanup pass applied to the refined mask.

Default: {"enabled":true,"size":512}

Nested fields

enabledboolean

Default: true

sizeinteger

Default: 512

Range: 128 to 1024

formatsarray

Derived formats to regenerate. Omit to infer the active formats already linked to the video.

Items: 1 to unbounded

Nested fields

string · webm, hevc, stacked_video, lottie, dotlottie

sizesarray

Size variants to regenerate. Omit to infer active linked sizes, so all currently used variants are refreshed.

Nested fields

integer

archive_oldboolean

Archive and unlink old matching derived assets after replacement assets are successfully published.

Default: true

dry_runboolean

Return the exact refinement/export plan without starting the workflow.

Default: true

Responses

200 Canvas edge mask refinement dry-run plan returned

application/json

dataobject · required

Nested fields

targetstring · required

Values: "video_mask_refinement"

dry_runboolean · required

video_asset_idstring · uuid · required

bg_job_idstring · required

promptstring · required

opstring · required

Values: "add", "subtract"

modelstring · required

Values: "original", "pro"

edge_cleanupobject

Nested fields

enabledboolean · required

sizenumber · required

formatsarray · required

Nested fields

string · webm, hevc, stacked_video, lottie, dotlottie

sizesarray · required

Nested fields

number

export_countnumber · required

archive_oldboolean · required

active_variantsarray · required

Nested fields

idstring · uuid · required

typestring · required

sizenumber

bgJobIdstring

canvasobject

Nested fields

collectionIdstring · uuid

canvasIdstring · uuid

edgeIdstring

in_flightobject

Nested fields

job_idstring · uuid · required

poll_urlstring · required

job_idstring · uuid

poll_urlstring

202 Canvas edge mask refinement job started

application/json

dataobject · required

Nested fields

targetstring · required

Values: "video_mask_refinement"

dry_runboolean · required

video_asset_idstring · uuid · required

bg_job_idstring · required

promptstring · required

opstring · required

Values: "add", "subtract"

modelstring · required

Values: "original", "pro"

edge_cleanupobject

Nested fields

enabledboolean · required

sizenumber · required

formatsarray · required

Nested fields

string · webm, hevc, stacked_video, lottie, dotlottie

sizesarray · required

Nested fields

number

export_countnumber · required

archive_oldboolean · required

active_variantsarray · required

Nested fields

idstring · uuid · required

typestring · required

sizenumber

bgJobIdstring

canvasobject

Nested fields

collectionIdstring · uuid

canvasIdstring · uuid

edgeIdstring

in_flightobject

Nested fields

job_idstring · uuid · required

poll_urlstring · required

job_idstring · uuid

poll_urlstring

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Canvases"
  ],
  "summary": "Refine a canvas edge video mask",
  "description": "Convenience wrapper around `POST /v1/assets/{id}/refine-mask` for a canvas edge. The route resolves the edge `videoAssetId`, refines that video asset mask, and re-exports the active derived formats/sizes. The canvas graph keeps the same raw video asset; desktop playback updates because the active linked WebM/HEVC/stacked variants are replaced underneath it. Any State and reverse edges are rejected because they do not own an independent video asset.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "canvasId",
      "in": "path"
    },
    {
      "schema": {
        "type": "string"
      },
      "required": true,
      "name": "edgeId",
      "in": "path"
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.",
      "schema": {
        "type": "string",
        "maxLength": 255
      }
    }
  ],
  "requestBody": {
    "required": true,
    "description": "Request body",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/RefineCanvasEdgeMaskBody"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Canvas edge mask refinement dry-run plan returned",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AssetMaskRefinementResponse"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "202": {
      "description": "Canvas edge mask refinement job started",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AssetMaskRefinementResponse"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    }
  },
  "deprecated": true,
  "operationId": "legacyRefineMaskCollectionCanvasEdge"
}

POST/v1/collections/{id}/canvases/{canvasId}/generate-allGenerate canvas images, stickers, and animations

Kicks off generation for pending canvas node images, sticker derivatives, and/or edge animations. Pass animation_model=standard (2 credits/sec, 2–15s) or premium (6 credits/sec, 4–30s); both default to 5s. Omit the field for legacy generation (5 credits/sec, 4–10s, default 4s). Model choice is included in plan approval and idempotent replay checks. Requires a write key in the collection workspace and project access, including for dry runs. Cross-workspace collections return 404. Use dry_run=true first to preview planned work, prompts, skipped items, and estimated credits without creating jobs/assets or spending credits. Dry-run returns plan_id and graph_content_hash; send them as approved_plan_id and expected_graph_hash on execution so a changed graph, prompt, option, or selection returns 409 before spending. Use targets="images" to generate poses, targets="stickers" to backfill transparent sticker derivatives for completed node images, targets="animations" for edge videos, or include_stickers=true to create stickers alongside newly generated images.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

canvasIdpath · required

string

Idempotency-Keyheader

string

Request body (required)

Request body

application/json

animation_modelstring

Same choices as Studio: standard costs 2 credits/sec (2–15s); premium costs 6 credits/sec (4–30s). Both default to 5s. Omit to preserve legacy generation at 5 credits/sec (4–10s, default 4s).

Values: "standard", "premium"

durationinteger

Range: 2 to 30

max_creditsnumber

Hard server-side credit ceiling. Execution fails before billing when the current work exceeds this limit.

Range: 0 to unbounded

skip_completedboolean

Deprecated compatibility flag. Canvas generate-all only dispatches missing work and always skips edges that already have assigned generated assets.

Default: true

include_stickersboolean

When true, generate sticker_image derivatives for generated image nodes.

Default: false

dry_runboolean

When true, only returns the planned work, prompts, skipped items, and estimated credit cost. Does not deduct credits, create jobs/assets/items, mutate the canvas graph, or start workflows.

Default: false

targetsstring

Which work to dispatch. "images" only generates skeleton node images. "stickers" backfills sticker_image derivatives for completed node images. "animations" only dispatches edge videos. "all" does both images and animations.

Values: "all", "images", "stickers", "animations"

Default: "all"

node_idsarray

Optional exact node selection. When present, only these nodes are considered for image or sticker work. Omit to consider every node.

Items: 1 to 100

Nested fields

string

edge_idsarray

Optional exact edge selection. When present, only these edges are considered for animation work. Omit to consider every edge.

Items: 1 to 200

Nested fields

string

expected_graph_hashstring

Optional graph revision returned by the dry-run plan. Execution returns 409 if the canvas changed after approval.

Length: 1 to unbounded characters

approved_plan_idstring

Optional generation plan identity returned by dry_run. Execution returns 409 unless the current graph, scope, prompts, duration, and generation options still match that approved plan.

Length: 1 to unbounded characters

Responses

200 Generation plan returned or jobs started

application/json

dataobject · required

Nested fields

plan_idstring

Stable identity of the exact graph, scope, prompts, and generation options. Return it as approved_plan_id when executing an approved dry-run plan.

graph_content_hashstring

Canvas revision used by this plan. Return it as expected_graph_hash when executing an approved dry-run plan.

dry_runboolean

can_dispatchboolean

targetsstring

Values: "all", "images", "stickers", "animations"

durationnumber

include_stickersboolean

skip_completedboolean

selectionobject

Nested fields

node_idsarray · nullable · required

Nested fields

string

edge_idsarray · nullable · required

Nested fields

string

jobsarray · required

Nested fields

job_idstring · uuid · required

edge_idstring

node_idstring

typestring · required

Values: "image", "edit", "sticker", "loop", "transition"

sourcestring

targetstring

item_namestring

costnumber · required

urlsobject

poll_urlstring

Follow this link to poll the job. On /v1/canvases routes it selects the mascot contract, so the job reports mascot_id.

generatedarray · required

Nested fields

object

planned_jobsarray

Nested fields

object

planned_job_countnumber

planned_nodesarray

Nested fields

object

planned_edgesarray

Nested fields

object

planned_stickersarray

Nested fields

object

skippednumber · required

skipped_itemsarray · required

Nested fields

kindstring · required

Values: "node", "edge"

idstring · required

reasonstring · required

asset_idstring · nullable

asset_statusstring

reverse_freearray · required

Nested fields

kindstring · required

Values: "edge"

idstring · required

reasonstring · required

Values: "reverse_edge_free"

reverse_of_edge_idstring · nullable · required

already_completearray · required

Nested fields

kindstring · required

Values: "node", "edge"

idstring · required

asset_idstring · required

estimated_costnumber · required

actual_costnumber · required

would_charge_creditsnumber

refunded_creditsnumber

total_jobsnumber · required

total_costnumber · required

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Canvases"
  ],
  "summary": "Generate canvas images, stickers, and animations",
  "description": "Kicks off generation for pending canvas node images, sticker derivatives, and/or edge animations. Pass animation_model=standard (2 credits/sec, 2–15s) or premium (6 credits/sec, 4–30s); both default to 5s. Omit the field for legacy generation (5 credits/sec, 4–10s, default 4s). Model choice is included in plan approval and idempotent replay checks. Requires a write key in the collection workspace and project access, including for dry runs. Cross-workspace collections return 404. Use `dry_run=true` first to preview planned work, prompts, skipped items, and estimated credits without creating jobs/assets or spending credits. Dry-run returns `plan_id` and `graph_content_hash`; send them as `approved_plan_id` and `expected_graph_hash` on execution so a changed graph, prompt, option, or selection returns 409 before spending. Use `targets=\"images\"` to generate poses, `targets=\"stickers\"` to backfill transparent sticker derivatives for completed node images, `targets=\"animations\"` for edge videos, or `include_stickers=true` to create stickers alongside newly generated images.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "canvasId",
      "in": "path"
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.",
      "schema": {
        "type": "string",
        "maxLength": 255
      }
    }
  ],
  "requestBody": {
    "required": true,
    "description": "Request body",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/GenerateAllBody"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Generation plan returned or jobs started",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CanvasGenerateAllResponse"
          },
          "example": {
            "data": {
              "jobs": [
                {
                  "job_id": "58341ab3-80fc-4fca-8a86-f9d2caee9a14",
                  "edge_id": "095872b7-c6f6-4f6d-8679-9739436fd16c",
                  "type": "transition",
                  "source": "Idle",
                  "target": "Waving",
                  "cost": 20,
                  "urls": {
                    "webm": "https://assets.masko.ai/fda8417d/cat-api-test-1776591702/idle---waving-a622eb51.webm",
                    "video": "https://assets.masko.ai/fda8417d/cat-api-test-1776591702/idle---waving-7e5fe2ec.mp4",
                    "hevc": "https://assets.masko.ai/fda8417d/cat-api-test-1776591702/idle---waving-2880976b.mov"
                  }
                }
              ],
              "total_jobs": 3,
              "total_cost": 60,
              "dry_run": false,
              "generated": [],
              "skipped": 0,
              "skipped_items": [],
              "reverse_free": [
                {
                  "kind": "edge",
                  "id": "waving-to-idle",
                  "reason": "reverse_edge_free",
                  "reverse_of_edge_id": "idle-to-waving"
                }
              ],
              "already_complete": [],
              "estimated_cost": 60,
              "would_charge_credits": 60,
              "actual_cost": 60
            }
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    }
  },
  "deprecated": true,
  "operationId": "legacyGenerateAllCollectionCanvas"
}

GET/v1/collections/{id}/canvases/{canvasId}/exportExport a canvas

Exports the canvas as a target-specific delivery envelope with delivery=1, the format the Masko player reads. Without delivery=1 it returns deprecated MaskoAnimationConfig JSON, kept for apps built on the old MaskoAnimation component, with a Deprecation: true header. No credit cost.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

canvasIdpath · required

string

formatquery

string · json

deliveryquery

Return the delivery envelope instead of legacy MaskoAnimationConfig data.

string · 1

targetquery

Delivery media target. android returns stacked MP4 URLs (colour above, transparency below) for Android players, apple and macos return HEVC URLs (apple for iPhone, iPad and Mac players), windows returns WebM URLs, web returns WebM and HEVC URLs, full returns WebM and HEVC URLs.

string · android, apple, macos, windows, web, full

modequery

Delivery mode. selected returns one variant; manifest includes known variants.

string · selected, manifest

sizequery

Selected delivery size in pixels, if that size variant has already been generated.

integer

Responses

200 Canvas export data

application/json

dataobject · required

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Canvases"
  ],
  "summary": "Export a canvas",
  "description": "Exports the canvas as a target-specific delivery envelope with delivery=1, the format the Masko player reads. Without delivery=1 it returns deprecated MaskoAnimationConfig JSON, kept for apps built on the old MaskoAnimation component, with a Deprecation: true header. No credit cost.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "canvasId",
      "in": "path"
    },
    {
      "schema": {
        "type": "string",
        "enum": [
          "json"
        ]
      },
      "required": false,
      "name": "format",
      "in": "query"
    },
    {
      "schema": {
        "type": "string",
        "enum": [
          "1"
        ],
        "description": "Return the delivery envelope instead of legacy MaskoAnimationConfig data."
      },
      "required": false,
      "description": "Return the delivery envelope instead of legacy MaskoAnimationConfig data.",
      "name": "delivery",
      "in": "query"
    },
    {
      "schema": {
        "type": "string",
        "enum": [
          "android",
          "apple",
          "macos",
          "windows",
          "web",
          "full"
        ],
        "description": "Delivery media target. android returns stacked MP4 URLs (colour above, transparency below) for Android players, apple and macos return HEVC URLs (apple for iPhone, iPad and Mac players), windows returns WebM URLs, web returns WebM and HEVC URLs, full returns WebM and HEVC URLs."
      },
      "required": false,
      "description": "Delivery media target. android returns stacked MP4 URLs (colour above, transparency below) for Android players, apple and macos return HEVC URLs (apple for iPhone, iPad and Mac players), windows returns WebM URLs, web returns WebM and HEVC URLs, full returns WebM and HEVC URLs.",
      "name": "target",
      "in": "query"
    },
    {
      "schema": {
        "type": "string",
        "enum": [
          "selected",
          "manifest"
        ],
        "description": "Delivery mode. selected returns one variant; manifest includes known variants."
      },
      "required": false,
      "description": "Delivery mode. selected returns one variant; manifest includes known variants.",
      "name": "mode",
      "in": "query"
    },
    {
      "schema": {
        "type": "integer",
        "minimum": 0,
        "exclusiveMinimum": true,
        "description": "Selected delivery size in pixels, if that size variant has already been generated."
      },
      "required": false,
      "description": "Selected delivery size in pixels, if that size variant has already been generated.",
      "name": "size",
      "in": "query"
    }
  ],
  "responses": {
    "200": {
      "description": "Canvas export data",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ExportConfigResponse"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    }
  },
  "deprecated": true,
  "operationId": "legacyGetCollectionCanvasExport"
}

GET/v1/canvas-templatesList canvas templates

Returns built-in templates plus any user-owned templates. Templates describe node prompts and edge definitions used to bootstrap canvases (e.g. "Essential Mascot", "Bonzi Buddy"). No credit cost.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

Masko-API-Versionheader

Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract.

string · 2026-09-26, legacy

api_versionquery

Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree.

string · 2026-09-26, legacy

Responses

200 List of canvas templates

application/json

dataarray · required

Nested fields

objectstring

Resource type. Always "canvas_template".

Values: "canvas_template"

idstring · required

namestring · required

descriptionstring · nullable · required

sourcestring · required

Values: "builtin", "user"

publicboolean

nodesarray

Nested fields

object

edgesarray

Nested fields

object

inputsarray

Nested fields

object

created_atstring

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Canvases"
  ],
  "summary": "List canvas templates",
  "description": "Returns built-in templates plus any user-owned templates. Templates describe node prompts and edge definitions used to bootstrap canvases (e.g. \"Essential Mascot\", \"Bonzi Buddy\"). No credit cost.\n\nSelect Masko-API-Version: 2026-09-26 (or api_version=2026-09-26) for the canonical mascot contract shown first. Existing unversioned clients keep legacy collection fields. A mascot_id query filter also selects the canonical contract. Mixing identifier names returns 400.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "responses": {
    "200": {
      "description": "List of canvas templates",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CanvasTemplateListResponse"
          },
          "example": {
            "data": [
              {
                "id": "bonzi-buddy-7state",
                "name": "Bonzi Buddy",
                "description": "7 animated poses with rich interactions: idle, coding, thinking, waving, celebrating, sleeping, and greeting on click. Classic Bonzi Buddy personality with sounds. ~340 credits.",
                "source": "builtin",
                "nodes": [
                  {
                    "key": "idle",
                    "name": "Idle",
                    "imagePrompt": "Standing casually, looking around curiously with big expressive eyes, slight swaying, hands at sides, friendly relaxed expression",
                    "position": {
                      "x": 0,
                      "y": 0
                    }
                  }
                ],
                "edges": []
              }
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    }
  },
  "operationId": "listCanvasTemplates",
  "parameters": [
    {
      "in": "header",
      "name": "Masko-API-Version",
      "required": false,
      "schema": {
        "type": "string",
        "enum": [
          "2026-09-26",
          "legacy"
        ]
      },
      "description": "Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract."
    },
    {
      "in": "query",
      "name": "api_version",
      "required": false,
      "schema": {
        "type": "string",
        "enum": [
          "2026-09-26",
          "legacy"
        ]
      },
      "description": "Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree."
    }
  ]
}

POST/v1/canvas-templatesCreate a canvas template

Creates a reusable user-owned canvas template. Templates can later be applied via POST /v1/mascots/{id}/canvases with template_id. No credit cost.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

Idempotency-Keyheader

string

Masko-API-Versionheader

Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract.

string · 2026-09-26, legacy

api_versionquery

Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree.

string · 2026-09-26, legacy

Request body (required)

Request body

application/json

StudioCreateTemplateBody

namestring · required

Template name.

Length: 1 to unbounded characters

descriptionstring

What the template does.

canvas_idstring · uuid

Existing canvas to snapshot. Required together with mascot_id. Mutually exclusive with template.

mascot_idstring · uuid

Source mascot for the snapshot. Required together with canvas_id.

templateobject

Raw template JSON. Provide this OR (canvas_id + collection_id).

publicboolean

If true, template is visible to all users. Defaults to false.

CreateTemplateBody

namestring · required

Template name.

Length: 1 to unbounded characters

descriptionstring

What the template does.

canvas_idstring · uuid

Existing canvas to snapshot. Required together with collection_id. Mutually exclusive with template.

collection_idstring · uuid

Source collection for the snapshot. Required together with canvas_id.

templateobject

Raw template JSON. Provide this OR (canvas_id + collection_id).

publicboolean

If true, template is visible to all users. Defaults to false.

Responses

201 Created template

application/json

dataobject · required

Nested fields

objectstring

Resource type. Always "canvas_template".

Values: "canvas_template"

idstring · required

namestring · required

descriptionstring · nullable · required

sourcestring · required

Values: "builtin", "user"

publicboolean

nodesarray

Nested fields

object

edgesarray

Nested fields

object

inputsarray

Nested fields

object

created_atstring

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Canvases"
  ],
  "summary": "Create a canvas template",
  "description": "Creates a reusable user-owned canvas template. Templates can later be applied via POST `/v1/mascots/{id}/canvases` with `template_id`. No credit cost.\n\nSelect Masko-API-Version: 2026-09-26 (or api_version=2026-09-26) for the canonical mascot contract shown first. Existing unversioned clients keep legacy collection fields. A mascot_id query filter also selects the canonical contract. Mixing identifier names returns 400.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "requestBody": {
    "required": true,
    "description": "Request body",
    "content": {
      "application/json": {
        "schema": {
          "anyOf": [
            {
              "$ref": "#/components/schemas/StudioCreateTemplateBody"
            },
            {
              "$ref": "#/components/schemas/CreateTemplateBody"
            }
          ]
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Created template",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CanvasTemplateResponse"
          },
          "example": {
            "data": {
              "id": "a5eba03f-8c29-481b-98b9-5cfc778cfcc7",
              "name": "test-template-tmp",
              "created_at": "2026-04-19T09:42:35.319739+00:00",
              "source": "user",
              "public": false
            }
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    }
  },
  "operationId": "createCanvasTemplate",
  "parameters": [
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.",
      "schema": {
        "type": "string",
        "maxLength": 255
      }
    },
    {
      "in": "header",
      "name": "Masko-API-Version",
      "required": false,
      "schema": {
        "type": "string",
        "enum": [
          "2026-09-26",
          "legacy"
        ]
      },
      "description": "Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract."
    },
    {
      "in": "query",
      "name": "api_version",
      "required": false,
      "schema": {
        "type": "string",
        "enum": [
          "2026-09-26",
          "legacy"
        ]
      },
      "description": "Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree."
    }
  ]
}

GET/v1/canvas-templates/{id}Get canvas template details

Returns the full template definition including node prompts, edges, and any declared inputs. Works for both built-in and user-owned templates. No credit cost.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

Masko-API-Versionheader

Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract.

string · 2026-09-26, legacy

api_versionquery

Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree.

string · 2026-09-26, legacy

Responses

200 Template details

application/json

dataobject · required

Nested fields

objectstring

Resource type. Always "canvas_template".

Values: "canvas_template"

idstring · required

namestring · required

descriptionstring · nullable · required

sourcestring · required

Values: "builtin", "user"

publicboolean

nodesarray

Nested fields

object

edgesarray

Nested fields

object

inputsarray

Nested fields

object

created_atstring

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Canvases"
  ],
  "summary": "Get canvas template details",
  "description": "Returns the full template definition including node prompts, edges, and any declared inputs. Works for both built-in and user-owned templates. No credit cost.\n\nSelect Masko-API-Version: 2026-09-26 (or api_version=2026-09-26) for the canonical mascot contract shown first. Existing unversioned clients keep legacy collection fields. A mascot_id query filter also selects the canonical contract. Mixing identifier names returns 400.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "in": "header",
      "name": "Masko-API-Version",
      "required": false,
      "schema": {
        "type": "string",
        "enum": [
          "2026-09-26",
          "legacy"
        ]
      },
      "description": "Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract."
    },
    {
      "in": "query",
      "name": "api_version",
      "required": false,
      "schema": {
        "type": "string",
        "enum": [
          "2026-09-26",
          "legacy"
        ]
      },
      "description": "Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree."
    }
  ],
  "responses": {
    "200": {
      "description": "Template details",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CanvasTemplateResponse"
          },
          "example": {
            "data": {
              "id": "claude-code-4state-lite",
              "name": "Essential Mascot",
              "description": "All 4 reactions (resting, coding, thinking, waving) at a lower cost. Uses smart routing to keep animations minimal. ~144 credits.",
              "source": "builtin",
              "nodes": [
                {
                  "key": "idle",
                  "name": "Idle",
                  "imagePrompt": "Relaxed, calm, sitting on the floor or resting, eyes half-open, peaceful expression, breathing gently",
                  "position": {
                    "x": 0,
                    "y": 0
                  }
                }
              ],
              "edges": [],
              "inputs": [
                {
                  "name": "claudeCode::isWorking",
                  "type": "boolean",
                  "default": false,
                  "system": true
                }
              ]
            }
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    }
  },
  "operationId": "getCanvasTemplate"
}

PATCH/v1/canvas-templates/{id}Update a canvas template

Updates name, description, public flag, or the template graph for a user-owned template. Built-in templates cannot be modified (returns 403). No credit cost.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

Masko-API-Versionheader

Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract.

string · 2026-09-26, legacy

api_versionquery

Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree.

string · 2026-09-26, legacy

Request body (required)

Request body

application/json

namestring

New template name.

Length: 1 to unbounded characters

descriptionstring

Updated description.

templateobject

Replacement template JSON.

publicboolean

Toggle whether template is visible to all users.

Responses

200 Template updated

application/json

dataobject · required

Nested fields

objectstring

Resource type. Always "canvas_template".

Values: "canvas_template"

idstring · required

namestring · required

descriptionstring · nullable · required

sourcestring · required

Values: "builtin", "user"

publicboolean

nodesarray

Nested fields

object

edgesarray

Nested fields

object

inputsarray

Nested fields

object

created_atstring

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Canvases"
  ],
  "summary": "Update a canvas template",
  "description": "Updates name, description, public flag, or the template graph for a user-owned template. Built-in templates cannot be modified (returns 403). No credit cost.\n\nSelect Masko-API-Version: 2026-09-26 (or api_version=2026-09-26) for the canonical mascot contract shown first. Existing unversioned clients keep legacy collection fields. A mascot_id query filter also selects the canonical contract. Mixing identifier names returns 400.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "in": "header",
      "name": "Masko-API-Version",
      "required": false,
      "schema": {
        "type": "string",
        "enum": [
          "2026-09-26",
          "legacy"
        ]
      },
      "description": "Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract."
    },
    {
      "in": "query",
      "name": "api_version",
      "required": false,
      "schema": {
        "type": "string",
        "enum": [
          "2026-09-26",
          "legacy"
        ]
      },
      "description": "Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree."
    }
  ],
  "requestBody": {
    "required": true,
    "description": "Request body",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/UpdateTemplateBody"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Template updated",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CanvasTemplateResponse"
          },
          "example": {
            "data": {
              "id": "a5eba03f-8c29-481b-98b9-5cfc778cfcc7",
              "user_id": "fda8417d-8789-4dce-aa64-c553a3de2ac0",
              "name": "test-template-tmp",
              "description": "Updated description",
              "template": {
                "edges": [
                  {
                    "source": "a",
                    "target": "a",
                    "duration": 4,
                    "description": "A idling"
                  }
                ],
                "nodes": [
                  {
                    "key": "a",
                    "name": "A",
                    "position": {
                      "x": 0,
                      "y": 0
                    },
                    "imagePrompt": "pose A"
                  }
                ],
                "inputs": []
              },
              "public": false,
              "created_at": "2026-04-19T09:42:35.319739+00:00",
              "updated_at": "2026-04-19T09:42:35.319739+00:00"
            }
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    }
  },
  "operationId": "updateCanvasTemplate"
}

DELETE/v1/canvas-templates/{id}Delete a canvas template

Deletes a user-owned template. Built-in templates cannot be deleted (returns 403). Returns 204. No credit cost.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

Masko-API-Versionheader

Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract.

string · 2026-09-26, legacy

api_versionquery

Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree.

string · 2026-09-26, legacy

Responses

204 Template deleted

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Canvases"
  ],
  "summary": "Delete a canvas template",
  "description": "Deletes a user-owned template. Built-in templates cannot be deleted (returns 403). Returns 204. No credit cost.\n\nSelect Masko-API-Version: 2026-09-26 (or api_version=2026-09-26) for the canonical mascot contract shown first. Existing unversioned clients keep legacy collection fields. A mascot_id query filter also selects the canonical contract. Mixing identifier names returns 400.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "in": "header",
      "name": "Masko-API-Version",
      "required": false,
      "schema": {
        "type": "string",
        "enum": [
          "2026-09-26",
          "legacy"
        ]
      },
      "description": "Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract."
    },
    {
      "in": "query",
      "name": "api_version",
      "required": false,
      "schema": {
        "type": "string",
        "enum": [
          "2026-09-26",
          "legacy"
        ]
      },
      "description": "Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree."
    }
  ],
  "responses": {
    "204": {
      "description": "Template deleted",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    }
  },
  "operationId": "deleteCanvasTemplate"
}

GET/v1/jobsList generation jobs

Returns paginated generation jobs owned by the caller, newest first. Use to track recent activity or find a specific job. Filter by status or mascot. No credit cost.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

limitquery

Page size. 1 to 100. Defaults to 50.

number

offsetquery

Number of records to skip. Defaults to 0.

number

cursorquery

Opaque next_cursor from the previous page. Use instead of offset.

string

from_variant_idquery

Filter transitions by the variant of the starting pose.

string

to_variant_idquery

Filter transitions by the variant of the ending pose.

string

variant_idquery

Filter jobs by their single variant. Cross-variant transitions have no single variant; use from_variant_id or to_variant_id.

string

statusquery

Filter by status: pending, processing, completed, failed.

string

mascot_idquery

Filter to jobs for a mascot in the credential workspace. A mascot outside that workspace returns 404.

string

typequery

Filter by job type. Values: item_generation, image_generation, logo, animation, video_edit, reverse, size_variant, size_variant_batch, export_animation, background_generation, interactive_generation, sticker_generation, svg_generation.

string

Masko-API-Versionheader

Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract.

string · 2026-09-26, legacy

api_versionquery

Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree.

string · 2026-09-26, legacy

collection_idquery

Legacy-only filter. Use mascot_id for new clients; never send both.

string

Responses

200 List of jobs

application/json

StudioJobListResponse

dataarray · required

Nested fields

objectstring

Resource type. Always "job".

Values: "job"

variant_idstring · uuid · nullable · required

Selected mascot variant, or null for original-context and older untagged jobs.

generation_contextobject

Frozen generation context: variant id and name, engine hash, the mascot prompt and style you provided, reference asset IDs and asset inputs. Transitions include transition.before and transition.after with pose IDs and saved variant contexts; video edits add transition_edit with the source video and requested edit. Internal generation execution details are never included.

idstring · uuid · required

statusstring · required

Values: "pending", "processing", "completed", "failed"

typestring · required

Values: "item_generation", "image_generation", "logo", "animation", "video_edit", "reverse", "size_variant", "size_variant_batch", "export_animation", "scene_generation", "background_generation", "sticker_generation", "svg_generation", "interactive_generation", "re_export", "canvas_orchestration", "mascot_brand_book"

mascot_idstring · uuid · nullable · required

cost_creditsnumber · required

created_atstring · required

updated_atstring · required

item_idstring · uuid · nullable

item_namestring · nullable

errorstring · nullable

urlsobject

file_sizesobject

Size in bytes of each file in urls, under the same key; null when the file cannot be read.

stepstring · nullable

mascot_brand_book jobs: pages (turning files into pages), read (free reading), generate (paid images), mascot (filling its context).

Values: "pages", "read", "generate", "mascot", "failed", null

resultobject

Completed mascot_brand_book jobs: the mascot created.

Nested fields

mascot_idstring · uuid · required

mascot_namestring · required

referencesinteger · required

Generated views saved as labeled references.

propsinteger · required

Generated props saved.

credits_chargedinteger · required

After refunds for images that failed.

metaobject · required

Nested fields

paginationobject

Nested fields

totalinteger · required

Range: 0 to unbounded

limitinteger · required

Range: 0 to unbounded

offsetinteger · required

Range: 0 to unbounded

has_moreboolean · required

next_cursorstring · nullable

Pass as the cursor query parameter to get the next page. Null on the last page.

JobListResponse

dataarray · required

Nested fields

objectstring

Resource type. Always "job".

Values: "job"

variant_idstring · uuid · nullable · required

Selected mascot variant, or null for original-context and older untagged jobs.

generation_contextobject

idstring · uuid · required

statusstring · required

Values: "pending", "processing", "completed", "failed"

typestring · required

collection_idstring · uuid · nullable · required

cost_creditsnumber · required

created_atstring · required

updated_atstring · required

item_idstring · uuid · nullable

item_namestring · nullable

errorstring · nullable

urlsobject

file_sizesobject

Size in bytes of each file in urls, under the same key; null when the file cannot be read.

stepstring · nullable

mascot_brand_book jobs: pages (turning files into pages), read (free reading), generate (paid images), mascot (filling its context).

Values: "pages", "read", "generate", "mascot", "failed", null

resultobject

Completed mascot_brand_book jobs: the mascot created.

Nested fields

mascot_idstring · uuid · required

mascot_namestring · required

referencesinteger · required

Generated views saved as labeled references.

propsinteger · required

Generated props saved.

credits_chargedinteger · required

After refunds for images that failed.

metaobject · required

Nested fields

paginationobject

Nested fields

totalinteger · required

Range: 0 to unbounded

limitinteger · required

Range: 0 to unbounded

offsetinteger · required

Range: 0 to unbounded

has_moreboolean · required

next_cursorstring · nullable

Pass as the cursor query parameter to get the next page. Null on the last page.

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Jobs"
  ],
  "summary": "List generation jobs",
  "description": "Returns paginated generation jobs owned by the caller, newest first. Use to track recent activity or find a specific job. Filter by status or mascot. No credit cost.\n\nSelect Masko-API-Version: 2026-09-26 (or api_version=2026-09-26) for the canonical mascot contract shown first. Existing unversioned clients keep legacy collection fields. A mascot_id query filter also selects the canonical contract. Mixing identifier names returns 400.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "number",
        "minimum": 1,
        "maximum": 100,
        "default": 50,
        "description": "Page size. 1 to 100. Defaults to 50."
      },
      "required": false,
      "description": "Page size. 1 to 100. Defaults to 50.",
      "name": "limit",
      "in": "query"
    },
    {
      "schema": {
        "type": "number",
        "nullable": true,
        "minimum": 0,
        "default": 0,
        "description": "Number of records to skip. Defaults to 0."
      },
      "required": false,
      "description": "Number of records to skip. Defaults to 0.",
      "name": "offset",
      "in": "query"
    },
    {
      "schema": {
        "type": "string",
        "description": "Opaque next_cursor from the previous page. Use instead of offset."
      },
      "required": false,
      "description": "Opaque next_cursor from the previous page. Use instead of offset.",
      "name": "cursor",
      "in": "query"
    },
    {
      "schema": {
        "type": "string",
        "format": "uuid",
        "description": "Filter transitions by the variant of the starting pose."
      },
      "required": false,
      "description": "Filter transitions by the variant of the starting pose.",
      "name": "from_variant_id",
      "in": "query"
    },
    {
      "schema": {
        "type": "string",
        "format": "uuid",
        "description": "Filter transitions by the variant of the ending pose."
      },
      "required": false,
      "description": "Filter transitions by the variant of the ending pose.",
      "name": "to_variant_id",
      "in": "query"
    },
    {
      "schema": {
        "type": "string",
        "format": "uuid",
        "description": "Filter jobs by their single variant. Cross-variant transitions have no single variant; use from_variant_id or to_variant_id."
      },
      "required": false,
      "description": "Filter jobs by their single variant. Cross-variant transitions have no single variant; use from_variant_id or to_variant_id.",
      "name": "variant_id",
      "in": "query"
    },
    {
      "schema": {
        "type": "string",
        "description": "Filter by status: pending, processing, completed, failed."
      },
      "required": false,
      "description": "Filter by status: pending, processing, completed, failed.",
      "name": "status",
      "in": "query"
    },
    {
      "schema": {
        "type": "string",
        "format": "uuid",
        "description": "Filter to jobs for a mascot in the credential workspace. A mascot outside that workspace returns 404."
      },
      "required": false,
      "description": "Filter to jobs for a mascot in the credential workspace. A mascot outside that workspace returns 404.",
      "name": "mascot_id",
      "in": "query"
    },
    {
      "schema": {
        "type": "string",
        "description": "Filter by job type. Values: item_generation, image_generation, logo, animation, video_edit, reverse, size_variant, size_variant_batch, export_animation, background_generation, interactive_generation, sticker_generation, svg_generation."
      },
      "required": false,
      "description": "Filter by job type. Values: item_generation, image_generation, logo, animation, video_edit, reverse, size_variant, size_variant_batch, export_animation, background_generation, interactive_generation, sticker_generation, svg_generation.",
      "name": "type",
      "in": "query"
    },
    {
      "in": "header",
      "name": "Masko-API-Version",
      "required": false,
      "schema": {
        "type": "string",
        "enum": [
          "2026-09-26",
          "legacy"
        ]
      },
      "description": "Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract."
    },
    {
      "in": "query",
      "name": "api_version",
      "required": false,
      "schema": {
        "type": "string",
        "enum": [
          "2026-09-26",
          "legacy"
        ]
      },
      "description": "Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree."
    },
    {
      "schema": {
        "type": "string",
        "format": "uuid",
        "description": "Filter to jobs for a mascot in the credential workspace. A mascot outside that workspace returns 404."
      },
      "required": false,
      "description": "Legacy-only filter. Use mascot_id for new clients; never send both.",
      "name": "collection_id",
      "in": "query",
      "deprecated": true
    }
  ],
  "responses": {
    "200": {
      "description": "List of jobs",
      "content": {
        "application/json": {
          "schema": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/StudioJobListResponse"
              },
              {
                "$ref": "#/components/schemas/JobListResponse"
              }
            ]
          },
          "example": {
            "data": [
              {
                "id": "ccc8bbf9-d3b2-4d8b-b21f-c5f91c5fbffa",
                "type": "background_generation",
                "status": "completed",
                "mascot_id": "21c247da-2359-47b2-97f9-da70bc1af688",
                "output_asset_id": null,
                "cost_credits": 3,
                "error": null,
                "created_at": "2026-04-14T11:14:49.18381+00:00",
                "updated_at": "2026-04-14T11:15:47.524116+00:00",
                "op_code": null,
                "input_data": {
                  "cost": 3,
                  "place": "phone_screen",
                  "description": "A misty bamboo forest at dawn",
                  "item_id": "7defa668-99ec-4f34-afa0-48599889958b",
                  "aspect_ratio": "9:19.5",
                  "collection_id": "21c247da-2359-47b2-97f9-da70bc1af688"
                },
                "output_data": {
                  "width": 1776,
                  "height": 3840,
                  "image_url": "image/png/5c08e718-acf3-4327-8ef5-895d0beefd4d.coach-ginger"
                }
              }
            ],
            "meta": {
              "pagination": {
                "total": 29,
                "limit": 5,
                "offset": 0,
                "has_more": true
              }
            }
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    }
  },
  "operationId": "listJobs"
}

GET/v1/jobs/{id}Long-poll a job to completion

Returns job status and output URLs. Pass ?wait=true to long-poll until the job completes or fails (up to ~60s). Returns 404 if the job does not exist or is not owned by the caller.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

waitquery

If true, long-poll until the job completes, fails, or timeout is reached. If false or omitted, return the current status immediately.

string · true, false

timeoutquery

Long-poll timeout in seconds when wait=true. 1 to 120. Defaults to 120. On timeout the response is 200 with the current (still pending) job state, not 408.

number

Masko-API-Versionheader

Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract.

string · 2026-09-26, legacy

api_versionquery

Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree.

string · 2026-09-26, legacy

Responses

200 Job details

application/json

StudioJobResponse

dataobject · required

Nested fields

objectstring

Resource type. Always "job".

Values: "job"

variant_idstring · uuid · nullable · required

Selected mascot variant, or null for original-context and older untagged jobs.

generation_contextobject

idstring · uuid · required

statusstring · required

Values: "pending", "processing", "completed", "failed"

typestring · required

mascot_idstring · uuid · nullable · required

cost_creditsnumber · required

created_atstring · required

updated_atstring · required

item_idstring · uuid · nullable

item_namestring · nullable

errorstring · nullable

urlsobject

file_sizesobject

Size in bytes of each file in urls, under the same key; null when the file cannot be read.

stepstring · nullable

mascot_brand_book jobs: pages (turning files into pages), read (free reading), generate (paid images), mascot (filling its context).

Values: "pages", "read", "generate", "mascot", "failed", null

resultobject

Completed mascot_brand_book jobs: the mascot created.

Nested fields

mascot_idstring · uuid · required

mascot_namestring · required

referencesinteger · required

Generated views saved as labeled references.

propsinteger · required

Generated props saved.

credits_chargedinteger · required

After refunds for images that failed.

JobResponse

dataobject · required

Nested fields

objectstring

Resource type. Always "job".

Values: "job"

variant_idstring · uuid · nullable · required

Selected mascot variant, or null for original-context and older untagged jobs.

generation_contextobject

idstring · uuid · required

statusstring · required

Values: "pending", "processing", "completed", "failed"

typestring · required

collection_idstring · uuid · nullable · required

cost_creditsnumber · required

created_atstring · required

updated_atstring · required

item_idstring · uuid · nullable

item_namestring · nullable

errorstring · nullable

urlsobject

file_sizesobject

Size in bytes of each file in urls, under the same key; null when the file cannot be read.

stepstring · nullable

mascot_brand_book jobs: pages (turning files into pages), read (free reading), generate (paid images), mascot (filling its context).

Values: "pages", "read", "generate", "mascot", "failed", null

resultobject

Completed mascot_brand_book jobs: the mascot created.

Nested fields

mascot_idstring · uuid · required

mascot_namestring · required

referencesinteger · required

Generated views saved as labeled references.

propsinteger · required

Generated props saved.

credits_chargedinteger · required

After refunds for images that failed.

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Jobs"
  ],
  "summary": "Long-poll a job to completion",
  "description": "Returns job status and output URLs. Pass `?wait=true` to long-poll until the job completes or fails (up to ~60s). Returns 404 if the job does not exist or is not owned by the caller.\n\nSelect Masko-API-Version: 2026-09-26 (or api_version=2026-09-26) for the canonical mascot contract shown first. Existing unversioned clients keep legacy collection fields. A mascot_id query filter also selects the canonical contract. Mixing identifier names returns 400.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "schema": {
        "type": "string",
        "enum": [
          "true",
          "false"
        ],
        "description": "If true, long-poll until the job completes, fails, or timeout is reached. If false or omitted, return the current status immediately."
      },
      "required": false,
      "description": "If true, long-poll until the job completes, fails, or timeout is reached. If false or omitted, return the current status immediately.",
      "name": "wait",
      "in": "query"
    },
    {
      "schema": {
        "type": "number",
        "minimum": 1,
        "maximum": 120,
        "description": "Long-poll timeout in seconds when wait=true. 1 to 120. Defaults to 120. On timeout the response is 200 with the current (still pending) job state, not 408."
      },
      "required": false,
      "description": "Long-poll timeout in seconds when wait=true. 1 to 120. Defaults to 120. On timeout the response is 200 with the current (still pending) job state, not 408.",
      "name": "timeout",
      "in": "query"
    },
    {
      "in": "header",
      "name": "Masko-API-Version",
      "required": false,
      "schema": {
        "type": "string",
        "enum": [
          "2026-09-26",
          "legacy"
        ]
      },
      "description": "Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract."
    },
    {
      "in": "query",
      "name": "api_version",
      "required": false,
      "schema": {
        "type": "string",
        "enum": [
          "2026-09-26",
          "legacy"
        ]
      },
      "description": "Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree."
    }
  ],
  "responses": {
    "200": {
      "description": "Job details",
      "content": {
        "application/json": {
          "schema": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/StudioJobResponse"
              },
              {
                "$ref": "#/components/schemas/JobResponse"
              }
            ]
          },
          "example": {
            "data": {
              "id": "ccc8bbf9-d3b2-4d8b-b21f-c5f91c5fbffa",
              "status": "completed",
              "type": "background_generation",
              "mascot_id": "21c247da-2359-47b2-97f9-da70bc1af688",
              "cost_credits": 3,
              "created_at": "2026-04-14T11:14:49.18381+00:00",
              "updated_at": "2026-04-14T11:15:47.524116+00:00",
              "item_id": "7defa668-99ec-4f34-afa0-48599889958b",
              "item_name": "Bamboo forest",
              "urls": {
                "image": "https://storage.googleapis.com/masco-media/image/png/5c08e718-acf3-4327-8ef5-895d0beefd4d.coach-ginger?GoogleAccessId=...&Expires=...&Signature=..."
              }
            }
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    }
  },
  "operationId": "getJob"
}

GET/v1/creditsGet credit balance

Returns current credits split into subscription (monthly allowance) and topup (purchased or bonus), plus total. Use before kicking off a large generation run to confirm balance. No credit cost.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

Masko-API-Versionheader

Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract.

string · 2026-09-26, legacy

api_versionquery

Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree.

string · 2026-09-26, legacy

Responses

200 Credit balance

application/json

dataobject · required

Nested fields

subscriptionnumber · required

topupnumber · required

totalnumber · required

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Credits"
  ],
  "summary": "Get credit balance",
  "description": "Returns current credits split into `subscription` (monthly allowance) and `topup` (purchased or bonus), plus `total`. Use before kicking off a large generation run to confirm balance. No credit cost.\n\nSelect Masko-API-Version: 2026-09-26 (or api_version=2026-09-26) for the canonical mascot contract shown first. Existing unversioned clients keep legacy collection fields. A mascot_id query filter also selects the canonical contract. Mixing identifier names returns 400.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "responses": {
    "200": {
      "description": "Credit balance",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CreditsResponse"
          },
          "example": {
            "data": {
              "subscription": 0,
              "topup": 894,
              "total": 894
            }
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    }
  },
  "operationId": "listCredits",
  "parameters": [
    {
      "in": "header",
      "name": "Masko-API-Version",
      "required": false,
      "schema": {
        "type": "string",
        "enum": [
          "2026-09-26",
          "legacy"
        ]
      },
      "description": "Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract."
    },
    {
      "in": "query",
      "name": "api_version",
      "required": false,
      "schema": {
        "type": "string",
        "enum": [
          "2026-09-26",
          "legacy"
        ]
      },
      "description": "Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree."
    }
  ]
}

GET/v1/stylesList available style presets

Returns all built-in style presets (cartoon, flat, pixel, kawaii, etc.) with preview URLs where available. Use id in generation prompts or as a style hint. No credit cost.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

Masko-API-Versionheader

Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract.

string · 2026-09-26, legacy

api_versionquery

Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree.

string · 2026-09-26, legacy

Responses

200 Available style presets

application/json

dataarray · required

Nested fields

idstring · required

namestring · required

descriptionstring

thumbnail_urlstring · uri

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Styles"
  ],
  "summary": "List available style presets",
  "description": "Returns all built-in style presets (cartoon, flat, pixel, kawaii, etc.) with preview URLs where available. Use `id` in generation prompts or as a style hint. No credit cost.\n\nSelect Masko-API-Version: 2026-09-26 (or api_version=2026-09-26) for the canonical mascot contract shown first. Existing unversioned clients keep legacy collection fields. A mascot_id query filter also selects the canonical contract. Mixing identifier names returns 400.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "responses": {
    "200": {
      "description": "Available style presets",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/StylesResponse"
          },
          "example": {
            "data": [
              {
                "id": "cartoon",
                "name": "Cartoon",
                "description": "Fun, colorful with bold outlines",
                "category": "classic",
                "preview_url": "https://assets.masko.ai/7fced6/budget-buddy-2702/think-2bb9ff25.png"
              },
              {
                "id": "flat",
                "name": "Flat",
                "description": "Clean, minimal, geometric",
                "category": "classic",
                "preview_url": "https://assets.masko.ai/7fced6/turbo-9bb8/encourage-0791d248.png"
              },
              {
                "id": "pixel",
                "name": "Pixel Art",
                "description": "Retro 8-bit video game style",
                "category": "retro",
                "preview_url": "https://assets.masko.ai/7fced6/pixel-runner-f1fb/flex-06183f7f.png"
              }
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    }
  },
  "operationId": "listStyles",
  "parameters": [
    {
      "in": "header",
      "name": "Masko-API-Version",
      "required": false,
      "schema": {
        "type": "string",
        "enum": [
          "2026-09-26",
          "legacy"
        ]
      },
      "description": "Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract."
    },
    {
      "in": "query",
      "name": "api_version",
      "required": false,
      "schema": {
        "type": "string",
        "enum": [
          "2026-09-26",
          "legacy"
        ]
      },
      "description": "Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree."
    }
  ]
}

POST/v1/uploadUpload an image, video or PDF

Accepts an image URL as JSON or an image/video file as multipart form data. Stores an asset owned by the caller and returns data.asset_id for use as a reference or source_asset_id. Malformed multipart data or a missing file returns 400. For a PDF such as a brand book, send JSON { "content_type": "application/pdf", "size": BYTES } instead: the response adds a signed upload_url, valid for 15 minutes, where you PUT the file with upload_headers. The file goes straight to storage, so it is not limited by the request body size; storage refuses it above 50 MB. Then pass asset_id to POST /v1/mascots/from-brand-book. No credit cost.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

Idempotency-Keyheader

string

Masko-API-Versionheader

Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract.

string · 2026-09-26, legacy

api_versionquery

Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree.

string · 2026-09-26, legacy

Request body (required)

application/json

UploadUrlBody

urlstring · uri · required

Public HTTP(S) image URL without credentials. Downloaded server-side with a 15-second deadline, public-address checks on every redirect, and a streamed 10MB limit. Private addresses are rejected. Images only (image/png, image/jpeg, image/webp, image/svg+xml, image/gif). SVGs are auto-converted to PNG. For video uploads or binary files, POST the same endpoint as multipart/form-data with a "file" field (max 10MB for images, 50MB for videos).

UploadSignedBody

content_typestring · required

Request a signed upload URL instead of sending the file. Only PDFs, such as brand books; images and videos are sent in the request body.

Values: "application/pdf"

sizeinteger · required

File size in bytes, at most 50 MB.

Range: 1 to 52428800

file_namestring

Original file name, kept with the upload.

Length: 1 to 200 characters

multipart/form-data

filestring · binary · required

Responses

200 Uploaded asset

application/json

dataobject · required

Nested fields

asset_idstring · uuid · required

upload_urlstring · uri

Signed upload only: PUT the file here with upload_headers before expires_at.

upload_methodstring

Values: "PUT"

upload_headersobject

Signed upload only: send exactly these headers with the PUT.

expires_atstring

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Upload"
  ],
  "summary": "Upload an image, video or PDF",
  "description": "Accepts an image URL as JSON or an image/video file as multipart form data. Stores an asset owned by the caller and returns `data.asset_id` for use as a reference or `source_asset_id`. Malformed multipart data or a missing file returns 400. For a PDF such as a brand book, send JSON `{ \"content_type\": \"application/pdf\", \"size\": BYTES }` instead: the response adds a signed `upload_url`, valid for 15 minutes, where you PUT the file with `upload_headers`. The file goes straight to storage, so it is not limited by the request body size; storage refuses it above 50 MB. Then pass `asset_id` to POST /v1/mascots/from-brand-book. No credit cost.\n\nSelect Masko-API-Version: 2026-09-26 (or api_version=2026-09-26) for the canonical mascot contract shown first. Existing unversioned clients keep legacy collection fields. A mascot_id query filter also selects the canonical contract. Mixing identifier names returns 400.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "anyOf": [
            {
              "$ref": "#/components/schemas/UploadUrlBody"
            },
            {
              "$ref": "#/components/schemas/UploadSignedBody"
            }
          ]
        }
      },
      "multipart/form-data": {
        "schema": {
          "type": "object",
          "properties": {
            "file": {
              "type": "string",
              "format": "binary"
            }
          },
          "required": [
            "file"
          ]
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Uploaded asset",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/UploadResponse"
          },
          "example": {
            "data": {
              "asset_id": "e906ebb5-deb1-4010-82f9-f0182a3812e0"
            }
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    }
  },
  "operationId": "upload",
  "parameters": [
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.",
      "schema": {
        "type": "string",
        "maxLength": 255
      }
    },
    {
      "in": "header",
      "name": "Masko-API-Version",
      "required": false,
      "schema": {
        "type": "string",
        "enum": [
          "2026-09-26",
          "legacy"
        ]
      },
      "description": "Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract."
    },
    {
      "in": "query",
      "name": "api_version",
      "required": false,
      "schema": {
        "type": "string",
        "enum": [
          "2026-09-26",
          "legacy"
        ]
      },
      "description": "Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree."
    }
  ]
}

POST/v1/generate/previewPreview an idea before creating a collection

Synchronous, throwaway image generation for iterating on mascot ideas cheaply before committing to a collection. No collection required. Tweak the prompt, regenerate, compare, then use the winning prompt + a reference image in POST /v1/collections. Also supports reference_image_urls to check "does this prompt resemble my sketch?". Returns signed URLs with a 1-hour expiry - the images are not stored. Costs 1 credit per image (the cost field in the response confirms the amount). Returns 402 if credits are insufficient.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

Idempotency-Keyheader

string

Request body (required)

Request body

application/json

promptstring · required

Text description of the mascot to preview. Preview exists for cheap idea iteration: tweak the prompt, regenerate, compare, then create the collection with the winning reference. Costs 1 credit per image generated.

Length: 1 to unbounded characters

preset_idstring

Optional style preset ID. List presets via GET /v1/styles.

countnumber

Number of preview variants to generate. 1 to 6. Defaults to 1.

Default: 1

Range: 1 to 6

reference_image_urlsarray

Optional "check against" images. Feed an image you want the mascot to resemble; the preview tries to match it. Useful for "does this prompt produce something close to my sketch?" iterations. Not stored - use POST /v1/collections/:id/references for persistent references.

Nested fields

string

Responses

200 Preview images

application/json

dataobject · required

Nested fields

imagesarray · required

Nested fields

urlstring · uri · required

expires_innumber · required

costnumber · required

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Generate"
  ],
  "summary": "Preview an idea before creating a collection",
  "description": "Synchronous, throwaway image generation for iterating on mascot ideas cheaply before committing to a collection. No collection required. Tweak the prompt, regenerate, compare, then use the winning prompt + a reference image in POST /v1/collections. Also supports `reference_image_urls` to check \"does this prompt resemble my sketch?\". Returns signed URLs with a 1-hour expiry - the images are not stored. Costs 1 credit per image (the `cost` field in the response confirms the amount). Returns 402 if credits are insufficient.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "requestBody": {
    "required": true,
    "description": "Request body",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/PreviewBody"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Preview images",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PreviewResponse"
          },
          "example": {
            "data": {
              "images": [
                {
                  "url": "https://storage.googleapis.com/masco-media/api-previews/.../3a0d33a8.jpeg?GoogleAccessId=...&Expires=...&Signature=...",
                  "expires_in": 3600
                }
              ],
              "cost": 1
            }
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "API version used to build this response.",
          "schema": {
            "type": "string",
            "example": "2026-09-26"
          }
        }
      }
    }
  },
  "operationId": "createGeneratePreview",
  "parameters": [
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.",
      "schema": {
        "type": "string",
        "maxLength": 255
      }
    }
  ]
}

POST/v1/analyzeAnalyze an image or website URL

Analyzes an image (by URL) or a public website and returns a description, style hints, a suggested mascot name, and a suggested prompt ready to feed into POST /v1/mascots. When type=url, the response also includes a screenshot (omitted from example for brevity). No credit cost.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

Idempotency-Keyheader

string

Masko-API-Versionheader

Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract.

string · 2026-09-26, legacy

api_versionquery

Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree.

string · 2026-09-26, legacy

Request body (required)

Request body

application/json

StudioAnalyzeBody

What to analyze. Use type="image" with image_url to analyze a mascot picture, or type="url" with url to analyze a brand website.

Option 1

typestring · required

Analyze a mascot/character image.

Values: "image"

image_urlstring · uri · required

Public image URL to analyze. Returns a structured description suitable for seeding a mascot prompt.

Option 2

typestring · required

Analyze a brand website.

Values: "url"

urlstring · uri · required

Website URL to analyze. Extracts brand colors, product description, and tone.

AnalyzeBody

What to analyze. Use type="image" with image_url to analyze a mascot picture, or type="url" with url to analyze a brand website.

Option 1

typestring · required

Analyze a mascot/character image.

Values: "image"

image_urlstring · uri · required

Public image URL to analyze. Returns a structured description suitable for seeding a collection prompt.

Option 2

typestring · required

Analyze a brand website.

Values: "url"

urlstring · uri · required

Website URL to analyze. Extracts brand colors, product description, and tone.

Responses

200 Analysis result (image or url)

application/json

AnalyzeImageResponse

dataobject · required

Nested fields

suggested_namestring · required

descriptionstring · required

style_hintsarray · required

Nested fields

string

suggested_promptstring · required

AnalyzeUrlResponse

dataobject · required

Nested fields

screenshotPathstring

markdownstring

metadataobject

descriptionstring

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Analyze"
  ],
  "summary": "Analyze an image or website URL",
  "description": "Analyzes an image (by URL) or a public website and returns a description, style hints, a suggested mascot name, and a suggested prompt ready to feed into POST `/v1/mascots`. When `type=url`, the response also includes a screenshot (omitted from example for brevity). No credit cost.\n\nSelect Masko-API-Version: 2026-09-26 (or api_version=2026-09-26) for the canonical mascot contract shown first. Existing unversioned clients keep legacy collection fields. A mascot_id query filter also selects the canonical contract. Mixing identifier names returns 400.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "requestBody": {
    "required": true,
    "description": "Request body",
    "content": {
      "application/json": {
        "schema": {
          "anyOf": [
            {
              "$ref": "#/components/schemas/StudioAnalyzeBody"
            },
            {
              "$ref": "#/components/schemas/AnalyzeBody"
            }
          ]
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Analysis result (image or url)",
      "content": {
        "application/json": {
          "schema": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/AnalyzeImageResponse"
              },
              {
                "$ref": "#/components/schemas/AnalyzeUrlResponse"
              }
            ]
          },
          "example": {
            "data": {
              "description": "A whimsical, wide-eyed ginger cat character designed with a claymation-like aesthetic. The cat features a plump, rounded body, a matte terracotta finish with fine dark speckles, and a charmingly surprised facial expression characterized by large circular eyes and thin, stylized whiskers.",
              "style_hints": [
                "Claymation",
                "Terracotta texture",
                "Matte finish",
                "Rounded minimalist forms",
                "Speckled surface",
                "Soft studio lighting",
                "3D sculpture"
              ],
              "suggested_name": "Terracotta Tom",
              "suggested_prompt": "A high-quality 3D render of a chubby ginger cat mascot in a claymation style. The cat is sitting, has a surprised expression with wide white eyes, a tiny pink nose, and thin clay whiskers. The material is matte terracotta orange with subtle dark speckles. Soft lighting, white background, clean minimalist aesthetic."
            }
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    }
  },
  "operationId": "analyze",
  "parameters": [
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.",
      "schema": {
        "type": "string",
        "maxLength": 255
      }
    },
    {
      "in": "header",
      "name": "Masko-API-Version",
      "required": false,
      "schema": {
        "type": "string",
        "enum": [
          "2026-09-26",
          "legacy"
        ]
      },
      "description": "Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract."
    },
    {
      "in": "query",
      "name": "api_version",
      "required": false,
      "schema": {
        "type": "string",
        "enum": [
          "2026-09-26",
          "legacy"
        ]
      },
      "description": "Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree."
    }
  ]
}

GET/v1/webhooksList webhook subscriptions

Returns all webhook subscriptions owned by the caller, including consecutive_failures and active flag. Webhooks are auto-deactivated after repeated delivery failures. No credit cost.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

Masko-API-Versionheader

Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract.

string · 2026-09-26, legacy

api_versionquery

Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree.

string · 2026-09-26, legacy

Responses

200 List of webhooks

application/json

dataarray · required

Nested fields

objectstring

Resource type. Always "webhook".

Values: "webhook"

idstring · uuid · required

urlstring · uri · required

eventsarray · required

Nested fields

string

activeboolean · required

consecutive_failuresnumber · required

created_atstring · required

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Webhooks"
  ],
  "summary": "List webhook subscriptions",
  "description": "Returns all webhook subscriptions owned by the caller, including `consecutive_failures` and `active` flag. Webhooks are auto-deactivated after repeated delivery failures. No credit cost.\n\nSelect Masko-API-Version: 2026-09-26 (or api_version=2026-09-26) for the canonical mascot contract shown first. Existing unversioned clients keep legacy collection fields. A mascot_id query filter also selects the canonical contract. Mixing identifier names returns 400.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "responses": {
    "200": {
      "description": "List of webhooks",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/WebhookListResponse"
          },
          "example": {
            "data": [
              {
                "id": "7c358096-8521-463c-b9c3-fd81bddaffc3",
                "url": "https://example.com",
                "events": [
                  "job.completed"
                ],
                "active": true,
                "consecutive_failures": 3,
                "created_at": "2026-04-08T03:31:26.284516+00:00"
              }
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    }
  },
  "operationId": "listWebhooks",
  "parameters": [
    {
      "in": "header",
      "name": "Masko-API-Version",
      "required": false,
      "schema": {
        "type": "string",
        "enum": [
          "2026-09-26",
          "legacy"
        ]
      },
      "description": "Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract."
    },
    {
      "in": "query",
      "name": "api_version",
      "required": false,
      "schema": {
        "type": "string",
        "enum": [
          "2026-09-26",
          "legacy"
        ]
      },
      "description": "Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree."
    }
  ]
}

POST/v1/webhooksCreate a webhook subscription

Creates a webhook subscription. Returns 201 with the subscription record including a one-time secret used to verify future HMAC signatures - store it immediately, it is never returned again. No credit cost.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

Idempotency-Keyheader

string

Masko-API-Versionheader

Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract.

string · 2026-09-26, legacy

api_versionquery

Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree.

string · 2026-09-26, legacy

Request body (required)

Request body

application/json

urlstring · uri · required

HTTPS URL that receives webhook POSTs as JSON. Each delivery includes Masko-Signature (t=<unix-seconds>,v1=<hmac-hex of "<t>.<body>">), X-Masko-Signature (sha256=<hmac-hex of body>), X-Masko-Timestamp, X-Masko-Event, and Masko-Event-Id headers. The body carries a stable event id that every retry reuses. A non-2xx response or network error is retried after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, and 12 hours. Auto-disables after 100 consecutive failed attempts.

eventsarray

Event types to subscribe to. Omit for all events. Available events: job.completed, job.failed.

Nested fields

string

Responses

201 Created webhook

application/json

dataobject · required

Nested fields

objectstring

Resource type. Always "webhook".

Values: "webhook"

idstring · uuid · required

urlstring · uri · required

eventsarray · required

Nested fields

string

activeboolean · required

consecutive_failuresnumber · required

created_atstring · required

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Webhooks"
  ],
  "summary": "Create a webhook subscription",
  "description": "Creates a webhook subscription. Returns 201 with the subscription record including a one-time `secret` used to verify future HMAC signatures - store it immediately, it is never returned again. No credit cost.\n\nSelect Masko-API-Version: 2026-09-26 (or api_version=2026-09-26) for the canonical mascot contract shown first. Existing unversioned clients keep legacy collection fields. A mascot_id query filter also selects the canonical contract. Mixing identifier names returns 400.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "requestBody": {
    "required": true,
    "description": "Request body",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/CreateWebhookBody"
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Created webhook",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/WebhookResponse"
          },
          "example": {
            "data": {
              "id": "5863639e-ad3f-4d4e-9bb3-12d0088d7d52",
              "url": "https://example.com/test-webhook",
              "events": [
                "job.completed",
                "job.failed"
              ],
              "created_at": "2026-04-19T09:42:34.430422+00:00",
              "secret": "whsec_3abe7a98aab0fcdb5c3b97142cf90dabccca37aa42974a198e7bdedb1148ce93"
            }
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    }
  },
  "operationId": "createWebhook",
  "parameters": [
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.",
      "schema": {
        "type": "string",
        "maxLength": 255
      }
    },
    {
      "in": "header",
      "name": "Masko-API-Version",
      "required": false,
      "schema": {
        "type": "string",
        "enum": [
          "2026-09-26",
          "legacy"
        ]
      },
      "description": "Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract."
    },
    {
      "in": "query",
      "name": "api_version",
      "required": false,
      "schema": {
        "type": "string",
        "enum": [
          "2026-09-26",
          "legacy"
        ]
      },
      "description": "Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree."
    }
  ]
}

DELETE/v1/webhooks/{id}Delete a webhook subscription

Removes the webhook subscription - no further events will be delivered. Returns 204. No credit cost.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

Masko-API-Versionheader

Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract.

string · 2026-09-26, legacy

api_versionquery

Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree.

string · 2026-09-26, legacy

Responses

204 Webhook deleted

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Webhooks"
  ],
  "summary": "Delete a webhook subscription",
  "description": "Removes the webhook subscription - no further events will be delivered. Returns 204. No credit cost.\n\nSelect Masko-API-Version: 2026-09-26 (or api_version=2026-09-26) for the canonical mascot contract shown first. Existing unversioned clients keep legacy collection fields. A mascot_id query filter also selects the canonical contract. Mixing identifier names returns 400.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "in": "header",
      "name": "Masko-API-Version",
      "required": false,
      "schema": {
        "type": "string",
        "enum": [
          "2026-09-26",
          "legacy"
        ]
      },
      "description": "Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract."
    },
    {
      "in": "query",
      "name": "api_version",
      "required": false,
      "schema": {
        "type": "string",
        "enum": [
          "2026-09-26",
          "legacy"
        ]
      },
      "description": "Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree."
    }
  ],
  "responses": {
    "204": {
      "description": "Webhook deleted",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26",
              "legacy"
            ]
          }
        }
      }
    }
  },
  "operationId": "deleteWebhook"
}

GET/v1/canvases/{canvasId}/validateValidate the stored canvas graph

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

canvasIdpath · required

string

Responses

200 Graph validation result.

application/json

dataobject · required

Nested fields

validboolean · required

issuesarray · required

Nested fields

severitystring · required

Values: "error", "warning"

codestring · required

messagestring · required

nodeIdstring

edgeIdstring

summaryobject · required

Nested fields

errorsnumber · required

warningsnumber · required

401 Missing or invalid credential.

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Insufficient credential permissions.

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Mascot or canvas not found in this workspace.

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

500 Validation could not be completed.

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Canvases"
  ],
  "summary": "Validate the stored canvas graph",
  "description": "Checks graph structure and assigned media references without generating media or changing the graph. Draft edges without videos report missing-video; this is expected before animation generation. GET requires read access. A structurally invalid graph still returns 200 with data.valid=false.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "canvasId",
      "in": "path"
    }
  ],
  "responses": {
    "200": {
      "description": "Graph validation result.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "valid": {
                    "type": "boolean"
                  },
                  "issues": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "severity": {
                          "type": "string",
                          "enum": [
                            "error",
                            "warning"
                          ]
                        },
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "nodeId": {
                          "type": "string"
                        },
                        "edgeId": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "severity",
                        "code",
                        "message"
                      ]
                    }
                  },
                  "summary": {
                    "type": "object",
                    "properties": {
                      "errors": {
                        "type": "number"
                      },
                      "warnings": {
                        "type": "number"
                      }
                    },
                    "required": [
                      "errors",
                      "warnings"
                    ]
                  }
                },
                "required": [
                  "valid",
                  "issues",
                  "summary"
                ]
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "401": {
      "description": "Missing or invalid credential.",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "403": {
      "description": "Insufficient credential permissions.",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "404": {
      "description": "Mascot or canvas not found in this workspace.",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "500": {
      "description": "Validation could not be completed.",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  },
  "operationId": "getCanvasValidate",
  "x-masko-api-version": "2026-09-26"
}

POST/v1/canvases/{canvasId}/validateValidate the stored canvas graph

Checks graph structure and assigned media references without generating media or changing the graph. Draft edges without videos report missing-video; this is expected before animation generation. POST requires write access and accepts no body; prefer GET for read-only checks. A structurally invalid graph still returns 200 with data.valid=false.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

canvasIdpath · required

string

Idempotency-Keyheader

string

Responses

200 Graph validation result.

application/json

dataobject · required

Nested fields

validboolean · required

issuesarray · required

Nested fields

severitystring · required

Values: "error", "warning"

codestring · required

messagestring · required

nodeIdstring

edgeIdstring

summaryobject · required

Nested fields

errorsnumber · required

warningsnumber · required

401 Missing or invalid credential.

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Insufficient credential permissions.

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Mascot or canvas not found in this workspace.

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

500 Validation could not be completed.

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Canvases"
  ],
  "summary": "Validate the stored canvas graph",
  "description": "Checks graph structure and assigned media references without generating media or changing the graph. Draft edges without videos report missing-video; this is expected before animation generation. POST requires write access and accepts no body; prefer GET for read-only checks. A structurally invalid graph still returns 200 with data.valid=false.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "canvasId",
      "in": "path"
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.",
      "schema": {
        "type": "string",
        "maxLength": 255
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Graph validation result.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "valid": {
                    "type": "boolean"
                  },
                  "issues": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "severity": {
                          "type": "string",
                          "enum": [
                            "error",
                            "warning"
                          ]
                        },
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "nodeId": {
                          "type": "string"
                        },
                        "edgeId": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "severity",
                        "code",
                        "message"
                      ]
                    }
                  },
                  "summary": {
                    "type": "object",
                    "properties": {
                      "errors": {
                        "type": "number"
                      },
                      "warnings": {
                        "type": "number"
                      }
                    },
                    "required": [
                      "errors",
                      "warnings"
                    ]
                  }
                },
                "required": [
                  "valid",
                  "issues",
                  "summary"
                ]
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "401": {
      "description": "Missing or invalid credential.",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "403": {
      "description": "Insufficient credential permissions.",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "404": {
      "description": "Mascot or canvas not found in this workspace.",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "500": {
      "description": "Validation could not be completed.",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  },
  "operationId": "validateCanvas",
  "x-masko-api-version": "2026-09-26"
}

POST/v1/canvases/{canvasId}/repairRepair canvas preview media

Plans or starts a narrow repair for missing base WebM/HEVC derivatives on videos already assigned to this canvas. Agent workflow: first call with dry_run=true or omit dry_run because it defaults to true. Read status.media.preview, summary, repairs, in_flight, and skipped. If status.media.preview.waiting_edges > 0, wait and poll again instead of repairing. Only call again with dry_run=false if the repair plan matches the intended canvas videos. This endpoint is for the specific case where status.media.generation.ready=true, status.media.preview.ready=false, and status.media.preview.repairable=true. It does not regenerate animations, does not run mascot-wide jobs, does not create size variants, does not expose prompt/model controls, does not force regeneration, and does not archive existing assets.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

canvasIdpath · required

string

Idempotency-Keyheader

string

Request body (required)

Request body

application/json

targetstring

Values: "video_derivatives"

Default: "video_derivatives"

formatsarray

Base derivative formats to repair. Defaults to both webm and hevc. This does not include size variants; optimized sizes must be generated through the size-variant flow.

Default: ["webm","hevc"]

Items: 1 to unbounded

Nested fields

string · webm, hevc

dry_runboolean

Default: true

Responses

200 Repair plan returned

application/json

dataobject · required

Nested fields

targetstring · required

Values: "video_derivatives"

dry_runboolean · required

formatsarray · required

Nested fields

string · webm, hevc

statusobject · required

Nested fields

generated_readyboolean · required

preview_readyboolean · required

mediaobject

Nested fields

generationobject · required

Nested fields

readyboolean · required

nodesobject · required

Nested fields

totalnumber · required

completednumber · required

pendingnumber · required

Incomplete node count. Includes failed nodes for backward compatibility; inspect failed for the terminal subset.

failednumber · required

edgesobject · required

Nested fields

totalnumber · required

completednumber · required

pendingnumber · required

failednumber · required

previewobject · required

Nested fields

readyboolean · required

repairableboolean · required

repairable_edgesnumber · required

waiting_edgesnumber · required

missing_edgesnumber · required

missing_formatsarray · required

Nested fields

string · webm, hevc

variantsobject · required

Nested fields

sizesarray · required

Nested fields

string

missingarray · required

Nested fields

edge_idstring · required

sizestring · required

formatsarray · required

Nested fields

See the OpenAPI schema for deeper nested fields.

summaryobject · required

Nested fields

edges_checkednumber · required

videos_checkednumber · required

videos_readynumber · required

videos_to_repairnumber · required

videos_in_flightnumber · required

videos_skippednumber · required

repairsarray · required

Nested fields

video_asset_idstring · uuid · required

edge_idsarray · required

Nested fields

string

missingarray · required

Nested fields

string · webm, hevc

actionstring · required

Values: "create_derivatives", "already_in_flight"

job_idstring · uuid

in_flightarray · required

Nested fields

video_asset_idstring · uuid · required

edge_idsarray · required

Nested fields

string

missingarray · required

Nested fields

string · webm, hevc

actionstring · required

Values: "create_derivatives", "already_in_flight"

job_idstring · uuid

skippedarray · required

Nested fields

video_asset_idstring · uuid · required

edge_idsarray · required

Nested fields

string

reasonstring · required

jobsarray

Nested fields

job_idstring · uuid · required

poll_urlstring · required

video_asset_idstring · uuid · required

edge_idsarray · required

Nested fields

string

formatsarray · required

Nested fields

string · webm, hevc

202 Repair jobs started

application/json

dataobject · required

Nested fields

targetstring · required

Values: "video_derivatives"

dry_runboolean · required

formatsarray · required

Nested fields

string · webm, hevc

statusobject · required

Nested fields

generated_readyboolean · required

preview_readyboolean · required

mediaobject

Nested fields

generationobject · required

Nested fields

readyboolean · required

nodesobject · required

Nested fields

totalnumber · required

completednumber · required

pendingnumber · required

Incomplete node count. Includes failed nodes for backward compatibility; inspect failed for the terminal subset.

failednumber · required

edgesobject · required

Nested fields

totalnumber · required

completednumber · required

pendingnumber · required

failednumber · required

previewobject · required

Nested fields

readyboolean · required

repairableboolean · required

repairable_edgesnumber · required

waiting_edgesnumber · required

missing_edgesnumber · required

missing_formatsarray · required

Nested fields

string · webm, hevc

variantsobject · required

Nested fields

sizesarray · required

Nested fields

string

missingarray · required

Nested fields

edge_idstring · required

sizestring · required

formatsarray · required

Nested fields

See the OpenAPI schema for deeper nested fields.

summaryobject · required

Nested fields

edges_checkednumber · required

videos_checkednumber · required

videos_readynumber · required

videos_to_repairnumber · required

videos_in_flightnumber · required

videos_skippednumber · required

repairsarray · required

Nested fields

video_asset_idstring · uuid · required

edge_idsarray · required

Nested fields

string

missingarray · required

Nested fields

string · webm, hevc

actionstring · required

Values: "create_derivatives", "already_in_flight"

job_idstring · uuid

in_flightarray · required

Nested fields

video_asset_idstring · uuid · required

edge_idsarray · required

Nested fields

string

missingarray · required

Nested fields

string · webm, hevc

actionstring · required

Values: "create_derivatives", "already_in_flight"

job_idstring · uuid

skippedarray · required

Nested fields

video_asset_idstring · uuid · required

edge_idsarray · required

Nested fields

string

reasonstring · required

jobsarray

Nested fields

job_idstring · uuid · required

poll_urlstring · required

video_asset_idstring · uuid · required

edge_idsarray · required

Nested fields

string

formatsarray · required

Nested fields

string · webm, hevc

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Canvases"
  ],
  "summary": "Repair canvas preview media",
  "description": "Plans or starts a narrow repair for missing base WebM/HEVC derivatives on videos already assigned to this canvas. Agent workflow: first call with `dry_run=true` or omit `dry_run` because it defaults to true. Read `status.media.preview`, `summary`, `repairs`, `in_flight`, and `skipped`. If `status.media.preview.waiting_edges > 0`, wait and poll again instead of repairing. Only call again with `dry_run=false` if the repair plan matches the intended canvas videos. This endpoint is for the specific case where `status.media.generation.ready=true`, `status.media.preview.ready=false`, and `status.media.preview.repairable=true`. It does not regenerate animations, does not run mascot-wide jobs, does not create size variants, does not expose prompt/model controls, does not force regeneration, and does not archive existing assets.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "canvasId",
      "in": "path"
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.",
      "schema": {
        "type": "string",
        "maxLength": 255
      }
    }
  ],
  "requestBody": {
    "required": true,
    "description": "Request body",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/RepairCanvasBody"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Repair plan returned",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CanvasRepairResponse"
          },
          "example": {
            "data": {
              "target": "video_derivatives",
              "dry_run": true,
              "formats": [
                "webm",
                "hevc"
              ],
              "status": {
                "generated_ready": true,
                "preview_ready": false,
                "media": {
                  "generation": {
                    "ready": true,
                    "nodes": {
                      "total": 6,
                      "completed": 6,
                      "pending": 0,
                      "failed": 0
                    },
                    "edges": {
                      "total": 42,
                      "completed": 42,
                      "pending": 0,
                      "failed": 0
                    }
                  },
                  "preview": {
                    "ready": false,
                    "repairable": true,
                    "repairable_edges": 2,
                    "waiting_edges": 0,
                    "missing_edges": 2,
                    "missing_formats": [
                      "webm",
                      "hevc"
                    ]
                  },
                  "variants": {
                    "sizes": [
                      "360"
                    ],
                    "missing": []
                  }
                }
              },
              "summary": {
                "edges_checked": 42,
                "videos_checked": 38,
                "videos_ready": 36,
                "videos_to_repair": 2,
                "videos_in_flight": 0,
                "videos_skipped": 0
              },
              "repairs": [
                {
                  "video_asset_id": "a98ba960-c1b3-4bf5-9e6f-1d57b43c651d",
                  "edge_ids": [
                    "enter-hover-perk"
                  ],
                  "missing": [
                    "webm",
                    "hevc"
                  ],
                  "action": "create_derivatives"
                }
              ],
              "in_flight": [],
              "skipped": []
            }
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "202": {
      "description": "Repair jobs started",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CanvasRepairResponse"
          },
          "example": {
            "data": {
              "target": "video_derivatives",
              "dry_run": false,
              "formats": [
                "webm",
                "hevc"
              ],
              "status": {
                "generated_ready": true,
                "preview_ready": false,
                "media": {
                  "generation": {
                    "ready": true,
                    "nodes": {
                      "total": 6,
                      "completed": 6,
                      "pending": 0,
                      "failed": 0
                    },
                    "edges": {
                      "total": 42,
                      "completed": 42,
                      "pending": 0,
                      "failed": 0
                    }
                  },
                  "preview": {
                    "ready": false,
                    "repairable": true,
                    "repairable_edges": 2,
                    "waiting_edges": 0,
                    "missing_edges": 2,
                    "missing_formats": [
                      "webm",
                      "hevc"
                    ]
                  },
                  "variants": {
                    "sizes": [
                      "360"
                    ],
                    "missing": []
                  }
                }
              },
              "summary": {
                "edges_checked": 42,
                "videos_checked": 38,
                "videos_ready": 36,
                "videos_to_repair": 2,
                "videos_in_flight": 0,
                "videos_skipped": 0
              },
              "repairs": [
                {
                  "video_asset_id": "a98ba960-c1b3-4bf5-9e6f-1d57b43c651d",
                  "edge_ids": [
                    "enter-hover-perk"
                  ],
                  "missing": [
                    "webm",
                    "hevc"
                  ],
                  "action": "create_derivatives"
                }
              ],
              "in_flight": [],
              "skipped": [],
              "jobs": [
                {
                  "job_id": "a1b2c3d4-0000-0000-0000-000000000001",
                  "poll_url": "/v1/jobs/a1b2c3d4-0000-0000-0000-000000000001?api_version=2026-09-26",
                  "video_asset_id": "a98ba960-c1b3-4bf5-9e6f-1d57b43c651d",
                  "edge_ids": [
                    "enter-hover-perk"
                  ],
                  "formats": [
                    "webm",
                    "hevc"
                  ]
                }
              ]
            }
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    }
  },
  "operationId": "repairCanvas",
  "x-masko-api-version": "2026-09-26"
}

POST/v1/canvases/{canvasId}/presentation/detect-facingDetect canvas natural facing

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

canvasIdpath · required

string

Idempotency-Keyheader

string

Responses

200 Suggested natural-facing presentation value

application/json

dataobject · required

Nested fields

suggestedNaturalFacingstring · required

Values: "left", "neutral", "right"

confidencenumber · required

warningstring

analyzedNodeCountinteger · required

Range: 0 to unbounded

nodeResultsarray · required

Nested fields

nodeIdstring · required

nodeNamestring · required

facingstring · required

Values: "left", "neutral", "right"

confidencenumber · required

reasonstring

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Canvases"
  ],
  "summary": "Detect canvas natural facing",
  "description": "Analyzes completed canvas node images and returns a suggested presentation.naturalFacing value plus node-level evidence. This is a synchronous analysis endpoint. It does not write to the canvas graph and has no credit cost.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "canvasId",
      "in": "path"
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.",
      "schema": {
        "type": "string",
        "maxLength": 255
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Suggested natural-facing presentation value",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CanvasFacingDetectionResponse"
          },
          "example": {
            "data": {
              "suggestedNaturalFacing": "left",
              "confidence": 0.82,
              "analyzedNodeCount": 3,
              "nodeResults": [
                {
                  "nodeId": "idle",
                  "nodeName": "Idle",
                  "facing": "left",
                  "confidence": 0.88,
                  "reason": "The mascot has a consistent left-facing body angle."
                }
              ]
            }
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    }
  },
  "operationId": "detectFacingCanvasPresentation",
  "x-masko-api-version": "2026-09-26"
}

POST/v1/canvases/{canvasId}/graph/extendLegacy partial canvas graph extension

Deprecated compatibility endpoint. New authoring clients should read the complete graph and graph_content_hash, reconcile locally, and PATCH the complete graph with expected_graph_hash.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

canvasIdpath · required

string

Idempotency-Keyheader

string

Request body (required)

Request body

application/json

add_nodesarray

Nodes to append. Fails if any node ID already exists.

Default: []

Nested fields

idstring · required

Length: 1 to unbounded characters

generationVariantIdstring · uuid

Approved variant in the same mascot used by generate-all for a new pose. Existing pose identity is preserved; completed assets are not regenerated.

add_edgesarray

Edges to append. Fails if any edge ID already exists.

Default: []

Nested fields

idstring · required

Length: 1 to unbounded characters

update_edgesarray

Partial edge patches keyed by id. Existing edge fields are preserved unless explicitly overwritten.

Default: []

Nested fields

idstring · required

Length: 1 to unbounded characters

add_inputsarray

Inputs to append. Existing input names are left unchanged.

Default: []

Nested fields

namestring · required

Length: 1 to unbounded characters

Responses

200 Canvas graph extended

application/json

dataobject · required

Nested fields

idstring · uuid · required

namestring · required

graphobject · required

updated_atstring · required

addedobject · required

Nested fields

nodesnumber · required

edgesnumber · required

inputsnumber · required

updatedobject · required

Nested fields

edgesnumber · required

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Canvases"
  ],
  "summary": "Legacy partial canvas graph extension",
  "deprecated": true,
  "description": "Deprecated compatibility endpoint. New authoring clients should read the complete graph and graph_content_hash, reconcile locally, and PATCH the complete graph with expected_graph_hash.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "canvasId",
      "in": "path"
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.",
      "schema": {
        "type": "string",
        "maxLength": 255
      }
    }
  ],
  "requestBody": {
    "required": true,
    "description": "Request body",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/StudioExtendCanvasGraphBody"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Canvas graph extended",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CanvasGraphExtendResponse"
          },
          "example": {
            "data": {
              "id": "280ceab9-4673-4c78-b37c-3617feb51914",
              "name": "Main canvas",
              "graph": {
                "nodes": [],
                "edges": [],
                "inputs": [],
                "viewport": {
                  "x": 0,
                  "y": 0,
                  "zoom": 1
                }
              },
              "updated_at": "2026-05-04T12:00:00.000Z",
              "added": {
                "nodes": 1,
                "edges": 2,
                "inputs": 1
              },
              "updated": {
                "edges": 1
              }
            }
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    }
  },
  "operationId": "extendCanvasGraph",
  "x-masko-api-version": "2026-09-26"
}

PATCH/v1/canvases/{canvasId}/edges/{edgeId}Patch a canvas edge

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

canvasIdpath · required

string

edgeIdpath · required

string

Request body (required)

Request body

application/json

speednumber

Playback speed multiplier for this edge. Normal transitions use 2, snappy interact transitions use 3-4, calm loops use 1.

Range: 0.1 to 10

speedInputstring · nullable

A number input declared in graph.inputs that this clip speed follows: it plays at speed times the value the app sets, kept between 0.2 and 4. null stops following one.

Length: 1 to unbounded characters

Responses

200 Canvas edge patched

application/json

dataobject · required

Nested fields

idstring · uuid · required

namestring · required

edgeobject · required

graphobject · required

updated_atstring · required

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Canvases"
  ],
  "summary": "Patch a canvas edge",
  "description": "Patches one edge without replacing the graph. Use this for speed tuning after generation: normal transitions use speed 2, snappy interact transitions use 3-4, held/special loops use 2, and calm loops use 1. speedInput ties the clip speed to a number input declared in graph.inputs, which the app sets at runtime (speed times that value, kept between 0.2 and 4); the next release carries it to the Masko players.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "canvasId",
      "in": "path"
    },
    {
      "schema": {
        "type": "string"
      },
      "required": true,
      "name": "edgeId",
      "in": "path"
    }
  ],
  "requestBody": {
    "required": true,
    "description": "Request body",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/PatchCanvasEdgeBody"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Canvas edge patched",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CanvasEdgePatchResponse"
          },
          "example": {
            "data": {
              "id": "280ceab9-4673-4c78-b37c-3617feb51914",
              "name": "Main canvas",
              "edge": {
                "id": "idle-to-interact",
                "source": "idle",
                "target": "interact",
                "duration": 4,
                "speed": 3
              },
              "graph": {
                "nodes": [],
                "edges": [],
                "inputs": [],
                "viewport": {
                  "x": 0,
                  "y": 0,
                  "zoom": 1
                }
              },
              "updated_at": "2026-05-04T12:00:00.000Z"
            }
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    }
  },
  "operationId": "updateCanvasEdge",
  "x-masko-api-version": "2026-09-26"
}

POST/v1/canvases/{canvasId}/edges/{edgeId}/generateGenerate a single canvas edge

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

canvasIdpath · required

string

edgeIdpath · required

string

Idempotency-Keyheader

string

Request body (required)

Request body

application/json

animation_modelstring

Same choices as Studio: standard costs 2 credits/sec (2–15s); premium costs 6 credits/sec (4–30s). Both default to 5s. Omit to preserve legacy generation at 5 credits/sec (4–10s, default 4s).

Values: "standard", "premium"

durationinteger

Range: 2 to 30

Responses

202 Edge generation started

application/json

dataobject · required

Nested fields

job_idstring · uuid · required

edge_idstring · required

typestring · required

Values: "loop", "transition"

sourcestring · required

targetstring · required

costnumber · required

urlsobject

poll_urlstring · required

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Canvases"
  ],
  "summary": "Generate a single canvas edge",
  "description": "Dispatches generation for one specific canvas edge by ID. Costs the same as a single edge in generate-all: duration * 2 for animation_model=standard or duration * 6 for premium. Without animation_model, legacy duration * 5 pricing is retained. If the edge already has a video asset, archives the old assets and re-dispatches. Any State edges (source: \"*\") and reverse edges are rejected with 400. Requires the source and target nodes to already have generated images. Loops use the source pose receipt, even on a mixed-variant canvas. Transitions retain both endpoint contexts. For uploads without receipts, the canvas context selects matching references; ambiguous shared uploads return 409 before charging.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "canvasId",
      "in": "path"
    },
    {
      "schema": {
        "type": "string"
      },
      "required": true,
      "name": "edgeId",
      "in": "path"
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.",
      "schema": {
        "type": "string",
        "maxLength": 255
      }
    }
  ],
  "requestBody": {
    "required": true,
    "description": "Request body",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/GenerateEdgeBody"
        }
      }
    }
  },
  "responses": {
    "202": {
      "description": "Edge generation started",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CanvasEdgeGenerateResponse"
          },
          "example": {
            "data": {
              "job_id": "a1b2c3d4-0000-0000-0000-000000000001",
              "edge_id": "idle-to-interact",
              "type": "transition",
              "source": "Idle",
              "target": "Interact",
              "cost": 20,
              "urls": {},
              "poll_url": "/v1/jobs/a1b2c3d4-0000-0000-0000-000000000001?api_version=2026-09-26"
            }
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    }
  },
  "operationId": "generateCanvasEdge",
  "x-masko-api-version": "2026-09-26"
}

POST/v1/canvases/{canvasId}/edges/{edgeId}/refine-maskRefine a canvas edge video mask

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

canvasIdpath · required

string

edgeIdpath · required

string

Idempotency-Keyheader

string

Request body (required)

Request body

application/json

opstring

Mask operation. add unions the prompted subject into the active mask; subtract removes it from the active mask.

Values: "add", "subtract"

Default: "add"

promptstring · required

Text prompt for the mask region to refine, e.g. "the soccer ball".

Length: 1 to unbounded characters

modelstring

Background mask refinement quality. Defaults to pro.

Values: "original", "pro"

Default: "pro"

edge_cleanupobject

Optional edge cleanup pass applied to the refined mask.

Default: {"enabled":true,"size":512}

Nested fields

enabledboolean

Default: true

sizeinteger

Default: 512

Range: 128 to 1024

formatsarray

Derived formats to regenerate. Omit to infer the active formats already linked to the video.

Items: 1 to unbounded

Nested fields

string · webm, hevc, stacked_video, lottie, dotlottie

sizesarray

Size variants to regenerate. Omit to infer active linked sizes, so all currently used variants are refreshed.

Nested fields

integer

archive_oldboolean

Archive and unlink old matching derived assets after replacement assets are successfully published.

Default: true

dry_runboolean

Return the exact refinement/export plan without starting the workflow.

Default: true

Responses

200 Canvas edge mask refinement dry-run plan returned

application/json

dataobject · required

Nested fields

targetstring · required

Values: "video_mask_refinement"

dry_runboolean · required

video_asset_idstring · uuid · required

bg_job_idstring · required

promptstring · required

opstring · required

Values: "add", "subtract"

modelstring · required

Values: "original", "pro"

edge_cleanupobject

Nested fields

enabledboolean · required

sizenumber · required

formatsarray · required

Nested fields

string · webm, hevc, stacked_video, lottie, dotlottie

sizesarray · required

Nested fields

number

export_countnumber · required

archive_oldboolean · required

active_variantsarray · required

Nested fields

idstring · uuid · required

typestring · required

sizenumber

bgJobIdstring

canvasobject

Nested fields

mascot_idstring · uuid

canvasIdstring · uuid

edgeIdstring

in_flightobject

Nested fields

job_idstring · uuid · required

poll_urlstring · required

job_idstring · uuid

poll_urlstring

202 Canvas edge mask refinement job started

application/json

dataobject · required

Nested fields

targetstring · required

Values: "video_mask_refinement"

dry_runboolean · required

video_asset_idstring · uuid · required

bg_job_idstring · required

promptstring · required

opstring · required

Values: "add", "subtract"

modelstring · required

Values: "original", "pro"

edge_cleanupobject

Nested fields

enabledboolean · required

sizenumber · required

formatsarray · required

Nested fields

string · webm, hevc, stacked_video, lottie, dotlottie

sizesarray · required

Nested fields

number

export_countnumber · required

archive_oldboolean · required

active_variantsarray · required

Nested fields

idstring · uuid · required

typestring · required

sizenumber

bgJobIdstring

canvasobject

Nested fields

mascot_idstring · uuid

canvasIdstring · uuid

edgeIdstring

in_flightobject

Nested fields

job_idstring · uuid · required

poll_urlstring · required

job_idstring · uuid

poll_urlstring

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Canvases"
  ],
  "summary": "Refine a canvas edge video mask",
  "description": "Convenience wrapper around `POST /v1/assets/{id}/refine-mask` for a canvas edge. The route resolves the edge `videoAssetId`, refines that video asset mask, and re-exports the active derived formats/sizes. The canvas graph keeps the same raw video asset; desktop playback updates because the active linked WebM/HEVC/stacked variants are replaced underneath it. Any State and reverse edges are rejected because they do not own an independent video asset.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "canvasId",
      "in": "path"
    },
    {
      "schema": {
        "type": "string"
      },
      "required": true,
      "name": "edgeId",
      "in": "path"
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.",
      "schema": {
        "type": "string",
        "maxLength": 255
      }
    }
  ],
  "requestBody": {
    "required": true,
    "description": "Request body",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/RefineCanvasEdgeMaskBody"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Canvas edge mask refinement dry-run plan returned",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/StudioAssetMaskRefinementResponse"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "202": {
      "description": "Canvas edge mask refinement job started",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/StudioAssetMaskRefinementResponse"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    }
  },
  "operationId": "refineMaskCanvasEdge",
  "x-masko-api-version": "2026-09-26"
}

POST/v1/canvases/{canvasId}/generate-allGenerate canvas images, stickers, and animations

Kicks off generation for pending canvas node images, sticker derivatives, and/or edge animations. Pass animation_model=standard (2 credits/sec, 2–15s) or premium (6 credits/sec, 4–30s); both default to 5s. Omit the field for legacy generation (5 credits/sec, 4–10s, default 4s). Model choice is included in plan approval and idempotent replay checks. Requires a write key in the mascot workspace and project access, including for dry runs. Cross-workspace mascots return 404. Use dry_run=true first to preview planned work, prompts, skipped items, and estimated credits without creating jobs/assets or spending credits. Dry-run returns plan_id and graph_content_hash; send them as approved_plan_id and expected_graph_hash on execution so a changed graph, prompt, option, or selection returns 409 before spending. Use targets="images" to generate poses, targets="stickers" to backfill transparent sticker derivatives for completed node images, targets="animations" for edge videos, or include_stickers=true to create stickers alongside newly generated images.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

canvasIdpath · required

string

Idempotency-Keyheader

string

Request body (required)

Request body

application/json

animation_modelstring

Same choices as Studio: standard costs 2 credits/sec (2–15s); premium costs 6 credits/sec (4–30s). Both default to 5s. Omit to preserve legacy generation at 5 credits/sec (4–10s, default 4s).

Values: "standard", "premium"

durationinteger

Range: 2 to 30

max_creditsnumber

Hard server-side credit ceiling. Execution fails before billing when the current work exceeds this limit.

Range: 0 to unbounded

skip_completedboolean

Deprecated compatibility flag. Canvas generate-all only dispatches missing work and always skips edges that already have assigned generated assets.

Default: true

include_stickersboolean

When true, generate sticker_image derivatives for generated image nodes.

Default: false

dry_runboolean

When true, only returns the planned work, prompts, skipped items, and estimated credit cost. Does not deduct credits, create jobs/assets/items, mutate the canvas graph, or start workflows.

Default: false

targetsstring

Values: "all", "images", "stickers", "animations"

Default: "all"

node_idsarray

Optional exact node selection. When present, only these nodes are considered for image or sticker work. Omit to consider every node.

Items: 1 to 100

Nested fields

string

edge_idsarray

Optional exact edge selection. When present, only these edges are considered for animation work. Omit to consider every edge.

Items: 1 to 200

Nested fields

string

expected_graph_hashstring

Optional graph revision returned by the dry-run plan. Execution returns 409 if the canvas changed after approval.

Length: 1 to unbounded characters

approved_plan_idstring

Optional generation plan identity returned by dry_run. Execution returns 409 unless the current graph, scope, prompts, duration, and generation options still match that approved plan.

Length: 1 to unbounded characters

Responses

200 Generation plan returned or jobs started

application/json

dataobject · required

Nested fields

plan_idstring

Stable identity of the exact graph, scope, prompts, and generation options. Return it as approved_plan_id when executing an approved dry-run plan.

graph_content_hashstring

Canvas revision used by this plan. Return it as expected_graph_hash when executing an approved dry-run plan.

dry_runboolean

can_dispatchboolean

targetsstring

Values: "all", "images", "stickers", "animations"

durationnumber

include_stickersboolean

skip_completedboolean

selectionobject

Nested fields

node_idsarray · nullable · required

Nested fields

string

edge_idsarray · nullable · required

Nested fields

string

jobsarray · required

Nested fields

job_idstring · uuid · required

edge_idstring

node_idstring

typestring · required

Values: "image", "edit", "sticker", "loop", "transition"

sourcestring

targetstring

item_namestring

costnumber · required

urlsobject

poll_urlstring

Follow this link to poll the job. On /v1/canvases routes it selects the mascot contract, so the job reports mascot_id.

generatedarray · required

Nested fields

object

planned_jobsarray

Nested fields

object

planned_job_countnumber

planned_nodesarray

Nested fields

object

planned_edgesarray

Nested fields

object

planned_stickersarray

Nested fields

object

skippednumber · required

skipped_itemsarray · required

Nested fields

kindstring · required

Values: "node", "edge"

idstring · required

reasonstring · required

asset_idstring · nullable

asset_statusstring

reverse_freearray · required

Nested fields

kindstring · required

Values: "edge"

idstring · required

reasonstring · required

Values: "reverse_edge_free"

reverse_of_edge_idstring · nullable · required

already_completearray · required

Nested fields

kindstring · required

Values: "node", "edge"

idstring · required

asset_idstring · required

estimated_costnumber · required

actual_costnumber · required

would_charge_creditsnumber

refunded_creditsnumber

total_jobsnumber · required

total_costnumber · required

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Canvases"
  ],
  "summary": "Generate canvas images, stickers, and animations",
  "description": "Kicks off generation for pending canvas node images, sticker derivatives, and/or edge animations. Pass animation_model=standard (2 credits/sec, 2–15s) or premium (6 credits/sec, 4–30s); both default to 5s. Omit the field for legacy generation (5 credits/sec, 4–10s, default 4s). Model choice is included in plan approval and idempotent replay checks. Requires a write key in the mascot workspace and project access, including for dry runs. Cross-workspace mascots return 404. Use `dry_run=true` first to preview planned work, prompts, skipped items, and estimated credits without creating jobs/assets or spending credits. Dry-run returns `plan_id` and `graph_content_hash`; send them as `approved_plan_id` and `expected_graph_hash` on execution so a changed graph, prompt, option, or selection returns 409 before spending. Use `targets=\"images\"` to generate poses, `targets=\"stickers\"` to backfill transparent sticker derivatives for completed node images, `targets=\"animations\"` for edge videos, or `include_stickers=true` to create stickers alongside newly generated images.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "canvasId",
      "in": "path"
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.",
      "schema": {
        "type": "string",
        "maxLength": 255
      }
    }
  ],
  "requestBody": {
    "required": true,
    "description": "Request body",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/GenerateAllBody"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Generation plan returned or jobs started",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CanvasGenerateAllResponse"
          },
          "example": {
            "data": {
              "jobs": [
                {
                  "job_id": "58341ab3-80fc-4fca-8a86-f9d2caee9a14",
                  "edge_id": "095872b7-c6f6-4f6d-8679-9739436fd16c",
                  "type": "transition",
                  "source": "Idle",
                  "target": "Waving",
                  "cost": 20,
                  "urls": {
                    "webm": "https://assets.masko.ai/fda8417d/cat-api-test-1776591702/idle---waving-a622eb51.webm",
                    "video": "https://assets.masko.ai/fda8417d/cat-api-test-1776591702/idle---waving-7e5fe2ec.mp4",
                    "hevc": "https://assets.masko.ai/fda8417d/cat-api-test-1776591702/idle---waving-2880976b.mov"
                  }
                }
              ],
              "total_jobs": 3,
              "total_cost": 60,
              "dry_run": false,
              "generated": [],
              "skipped": 0,
              "skipped_items": [],
              "reverse_free": [
                {
                  "kind": "edge",
                  "id": "waving-to-idle",
                  "reason": "reverse_edge_free",
                  "reverse_of_edge_id": "idle-to-waving"
                }
              ],
              "already_complete": [],
              "estimated_cost": 60,
              "would_charge_credits": 60,
              "actual_cost": 60
            }
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    }
  },
  "operationId": "generateAllCanvas",
  "x-masko-api-version": "2026-09-26"
}

GET/v1/canvases/{canvasId}/exportExport a canvas

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

canvasIdpath · required

string

formatquery

string · json

deliveryquery

Return the delivery envelope instead of legacy MaskoAnimationConfig data.

string · 1

targetquery

string · android, apple, macos, windows, web, full

modequery

Delivery mode. selected returns one variant; manifest includes known variants.

string · selected, manifest

sizequery

Selected delivery size in pixels, if that size variant has already been generated.

integer

Responses

200 Canvas export data

application/json

dataobject · required

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Canvases"
  ],
  "summary": "Export a canvas",
  "description": "Exports the canvas as a target-specific delivery envelope with delivery=1, the format the Masko player reads. Without delivery=1 it returns deprecated MaskoAnimationConfig JSON, kept for apps built on the old MaskoAnimation component, with a Deprecation: true header. No credit cost.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "canvasId",
      "in": "path"
    },
    {
      "schema": {
        "type": "string",
        "enum": [
          "json"
        ]
      },
      "required": false,
      "name": "format",
      "in": "query"
    },
    {
      "schema": {
        "type": "string",
        "enum": [
          "1"
        ],
        "description": "Return the delivery envelope instead of legacy MaskoAnimationConfig data."
      },
      "required": false,
      "description": "Return the delivery envelope instead of legacy MaskoAnimationConfig data.",
      "name": "delivery",
      "in": "query"
    },
    {
      "schema": {
        "type": "string",
        "enum": [
          "android",
          "apple",
          "macos",
          "windows",
          "web",
          "full"
        ],
        "description": "Delivery media target. android returns stacked MP4 URLs (colour above, transparency below) for Android players, apple and macos return HEVC URLs (apple for iPhone, iPad and Mac players), windows returns WebM URLs, web returns WebM and HEVC URLs, full returns WebM and HEVC URLs."
      },
      "required": false,
      "description": "Delivery media target. android returns stacked MP4 URLs (colour above, transparency below) for Android players, apple and macos return HEVC URLs (apple for iPhone, iPad and Mac players), windows returns WebM URLs, web returns WebM and HEVC URLs, full returns WebM and HEVC URLs.",
      "name": "target",
      "in": "query"
    },
    {
      "schema": {
        "type": "string",
        "enum": [
          "selected",
          "manifest"
        ],
        "description": "Delivery mode. selected returns one variant; manifest includes known variants."
      },
      "required": false,
      "description": "Delivery mode. selected returns one variant; manifest includes known variants.",
      "name": "mode",
      "in": "query"
    },
    {
      "schema": {
        "type": "integer",
        "minimum": 0,
        "exclusiveMinimum": true,
        "description": "Selected delivery size in pixels, if that size variant has already been generated."
      },
      "required": false,
      "description": "Selected delivery size in pixels, if that size variant has already been generated.",
      "name": "size",
      "in": "query"
    }
  ],
  "responses": {
    "200": {
      "description": "Canvas export data",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ExportConfigResponse"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    }
  },
  "operationId": "getCanvasExport",
  "x-masko-api-version": "2026-09-26"
}

GET/v1/mascots/{id}/variantsList named mascot variants

Lists the mascot’s named generation contexts. Variant authoring follows mascot project permissions, including authorized teammates; API keys must match the mascot workspace. Create and approve variants through the API or web app, then pass the id as variant_id to /generate. Selecting a generation variant does not change active playback. A null approved_at means the variant is still a draft.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

limitquery

Page size. 1 to 100. Defaults to 50.

number

offsetquery

Number of records to skip. Defaults to 0.

number

cursorquery

Opaque next_cursor from the previous page. Use instead of offset.

string

Responses

200 Variants in creation order

application/json

dataarray · required

Nested fields

idstring · uuid · required

namestring · required

descriptionstring · required

approved_atstring · nullable · required

canvas_idstring · uuid · nullable · required

reference_asset_idstring · uuid · nullable · required

created_atstring · required

metaobject · required

Nested fields

paginationobject · required

Nested fields

totalnumber · required

limitnumber · required

offsetnumber · required

has_moreboolean · required

401 Authentication required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Mascot not found in this workspace

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Mascots"
  ],
  "summary": "List named mascot variants",
  "description": "Lists the mascot’s named generation contexts. Variant authoring follows mascot project permissions, including authorized teammates; API keys must match the mascot workspace. Create and approve variants through the API or web app, then pass the id as variant_id to /generate. Selecting a generation variant does not change active playback. A null approved_at means the variant is still a draft.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "schema": {
        "type": "number",
        "minimum": 1,
        "maximum": 100,
        "default": 50,
        "description": "Page size. 1 to 100. Defaults to 50."
      },
      "required": false,
      "description": "Page size. 1 to 100. Defaults to 50.",
      "name": "limit",
      "in": "query"
    },
    {
      "schema": {
        "type": "number",
        "nullable": true,
        "minimum": 0,
        "default": 0,
        "description": "Number of records to skip. Defaults to 0."
      },
      "required": false,
      "description": "Number of records to skip. Defaults to 0.",
      "name": "offset",
      "in": "query"
    },
    {
      "schema": {
        "type": "string",
        "description": "Opaque next_cursor from the previous page. Use instead of offset."
      },
      "required": false,
      "description": "Opaque next_cursor from the previous page. Use instead of offset.",
      "name": "cursor",
      "in": "query"
    }
  ],
  "responses": {
    "200": {
      "description": "Variants in creation order",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/MascotVariant"
                }
              },
              "meta": {
                "type": "object",
                "properties": {
                  "pagination": {
                    "type": "object",
                    "properties": {
                      "total": {
                        "type": "number"
                      },
                      "limit": {
                        "type": "number"
                      },
                      "offset": {
                        "type": "number"
                      },
                      "has_more": {
                        "type": "boolean"
                      }
                    },
                    "required": [
                      "total",
                      "limit",
                      "offset",
                      "has_more"
                    ]
                  }
                },
                "required": [
                  "pagination"
                ]
              }
            },
            "required": [
              "data",
              "meta"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "401": {
      "description": "Authentication required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "404": {
      "description": "Mascot not found in this workspace",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  },
  "operationId": "listMascotVariants",
  "x-masko-api-version": "2026-09-26"
}

POST/v1/mascots/{id}/variantsCreate a named mascot variant

Creates a draft from Original or source_variant_id. The source context and references are frozen. Supply reference_asset_id to use an existing mascot image or your unassigned /v1/upload image and immediately approve the context, with no generation charge. Otherwise generate and approve a reference next. Reuse id for retries with the same inputs. This does not activate playback.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

Idempotency-Keyheader

string

Request body

application/json

idstring · uuid · required

Client-generated UUID. Reuse it to safely retry creation.

namestring · required

Length: 1 to 80 characters

descriptionstring · required

The desired change and generation guidance.

Length: 1 to 3000 characters

source_variant_idstring · uuid

Approved variant to start from. Omit for Original. Its references and context are frozen on creation.

reference_asset_idstring · uuid

Completed image in this mascot, or your unassigned POST /v1/upload image. Creates an approved context immediately; no generation charge. Omit to create a draft for reference generation.

Responses

201 Created variant

application/json

dataobject · required

Nested fields

idstring · uuid · required

namestring · required

descriptionstring · required

approved_atstring · nullable · required

canvas_idstring · uuid · nullable · required

reference_asset_idstring · uuid · nullable · required

created_atstring · required

400 Invalid request or reference

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Authentication required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Variant creator required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Mascot, variant or reference not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Draft source, changed operation inputs, or candidate not ready

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Mascots"
  ],
  "summary": "Create a named mascot variant",
  "description": "Creates a draft from Original or source_variant_id. The source context and references are frozen. Supply reference_asset_id to use an existing mascot image or your unassigned /v1/upload image and immediately approve the context, with no generation charge. Otherwise generate and approve a reference next. Reuse id for retries with the same inputs. This does not activate playback.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.",
      "schema": {
        "type": "string",
        "maxLength": 255
      }
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/StudioCreateMascotVariantBody"
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Created variant",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/MascotVariant"
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Invalid request or reference",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "401": {
      "description": "Authentication required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "403": {
      "description": "Variant creator required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "404": {
      "description": "Mascot, variant or reference not found",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "409": {
      "description": "Draft source, changed operation inputs, or candidate not ready",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  },
  "operationId": "createMascotVariant",
  "x-masko-api-version": "2026-09-26"
}

GET/v1/mascots/{id}/variants/{variantId}Read a variant and its reference candidates

Returns one variant with its reference candidates and approval state.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

variantIdpath · required

string

Responses

200 Variant and candidate previews

application/json

dataobject · required

Nested fields

variantobject · required

Nested fields

idstring · uuid · required

namestring · required

descriptionstring · required

approved_atstring · nullable · required

canvas_idstring · uuid · nullable · required

reference_asset_idstring · uuid · nullable · required

created_atstring · required

candidatesarray · required

Nested fields

idstring · uuid · required

asset_idstring · uuid · nullable · required

job_idstring · uuid · nullable · required

created_atstring · required

statusstring · required

errorstring · nullable

urlstring · nullable · required

400 Invalid request or reference

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Authentication required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Variant creator required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Mascot, variant or reference not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Draft source, changed operation inputs, or candidate not ready

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Mascots"
  ],
  "summary": "Read a variant and its reference candidates",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "variantId",
      "in": "path"
    }
  ],
  "responses": {
    "200": {
      "description": "Variant and candidate previews",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/MascotVariantDetail"
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Invalid request or reference",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "401": {
      "description": "Authentication required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "403": {
      "description": "Variant creator required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "404": {
      "description": "Mascot, variant or reference not found",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "409": {
      "description": "Draft source, changed operation inputs, or candidate not ready",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  },
  "operationId": "getMascotVariant",
  "description": "Returns one variant with its reference candidates and approval state.",
  "x-masko-api-version": "2026-09-26"
}

POST/v1/mascots/{id}/variants/{variantId}/referenceGenerate a draft variant reference

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

variantIdpath · required

string

Idempotency-Keyheader

string

Request body

application/json

operation_idstring · uuid · required

Client-generated UUID. Reuse to retry the same candidate job without another charge.

Responses

202 Reference generation queued

application/json

dataobject · required

Nested fields

job_idstring · uuid · required

candidate_idstring · uuid · required

variant_idstring · uuid · required

estimated_costnumber · required

poll_urlstring · required

400 Invalid request or reference

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Authentication required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

402 Not enough credits

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Variant creator required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Mascot, variant or reference not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Draft source, changed operation inputs, or candidate not ready

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Mascots"
  ],
  "summary": "Generate a draft variant reference",
  "description": "Costs 1 credit. Uses the frozen source references and the requested variant description. Reuse operation_id to retry the same job. Poll the job, inspect candidates with GET variant, then approve the selected candidate.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "variantId",
      "in": "path"
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.",
      "schema": {
        "type": "string",
        "maxLength": 255
      }
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/GenerateVariantReferenceBody"
        }
      }
    }
  },
  "responses": {
    "202": {
      "description": "Reference generation queued",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "job_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "candidate_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "variant_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "estimated_cost": {
                    "type": "number"
                  },
                  "poll_url": {
                    "type": "string"
                  }
                },
                "required": [
                  "job_id",
                  "candidate_id",
                  "variant_id",
                  "estimated_cost",
                  "poll_url"
                ]
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Invalid request or reference",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "401": {
      "description": "Authentication required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "402": {
      "description": "Not enough credits",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "403": {
      "description": "Variant creator required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "404": {
      "description": "Mascot, variant or reference not found",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "409": {
      "description": "Draft source, changed operation inputs, or candidate not ready",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  },
  "operationId": "createMascotVariantReference",
  "x-masko-api-version": "2026-09-26"
}

POST/v1/mascots/{id}/variants/{variantId}/approveApprove a generated variant reference

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

variantIdpath · required

string

Idempotency-Keyheader

string

Request body

application/json

candidate_idstring · uuid · required

Completed candidate from this variant to use as its reference.

Responses

200 Approved variant

application/json

dataobject · required

Nested fields

idstring · uuid · required

namestring · required

descriptionstring · required

approved_atstring · nullable · required

canvas_idstring · uuid · nullable · required

reference_asset_idstring · uuid · nullable · required

created_atstring · required

400 Invalid request or reference

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Authentication required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Variant creator required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Mascot, variant or reference not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Draft source, changed operation inputs, or candidate not ready

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Mascots"
  ],
  "summary": "Approve a generated variant reference",
  "description": "Select a completed candidate belonging to this variant. Creates its canvas and makes variant_id usable for generation. Does not generate poses or change active playback. Repeating approval of the same candidate is safe.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "variantId",
      "in": "path"
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.",
      "schema": {
        "type": "string",
        "maxLength": 255
      }
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApproveMascotVariantBody"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Approved variant",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/MascotVariant"
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Invalid request or reference",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "401": {
      "description": "Authentication required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "403": {
      "description": "Variant creator required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "404": {
      "description": "Mascot, variant or reference not found",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "409": {
      "description": "Draft source, changed operation inputs, or candidate not ready",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  },
  "operationId": "approveMascotVariant",
  "x-masko-api-version": "2026-09-26"
}

POST/v1/mascots/{id}/interactiveGenerate a follow-cursor interaction

Creates nine 1024×1024 transparent gaze directions from one completed image. Requires a completed transparent source or transparent derivative in the same mascot. Preserves the source variant automatically; no variant_id override. Optional name (maximum 60 characters after trimming) labels only the interaction; omitted or blank names use the source image name without renaming the image. Costs 9 credits. Returns an asynchronous job receipt. Send once and poll the returned job URL; repeating POST creates and charges a new set. Hosted mascots automatically publish a JSON manifest and nine lossless WebPs. Retrieve them with GET /v1/mascots/{id}/cdn-export after completion. This interaction is independent of Canvas state machines.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

Idempotency-Keyheader

string

Request body (required)

application/json

source_asset_idstring · uuid · required

kindstring · required

Values: "cursor-follower"

namestring

Interaction label. Omitted or blank names use the source image name without renaming the image.

Length: 0 to 60 characters

Responses

202 Nine-direction generation queued

application/json

dataobject · required

Nested fields

job_idstring · uuid · required

asset_idstring · uuid · required

asset_idsobject · required

Nested fields

interactivestring · uuid · required

statusstring · required

Values: "pending"

estimated_costnumber · required

variant_idstring · uuid · nullable · required

poll_urlstring · required

400 Invalid request

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

402 Insufficient credits

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Write access required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Mascot or completed source not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

422 Transparent image required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

429 Rate limited

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

500 Could not queue generation

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Generate"
  ],
  "summary": "Generate a follow-cursor interaction",
  "description": "Creates nine 1024×1024 transparent gaze directions from one completed image. Requires a completed transparent source or transparent derivative in the same mascot. Preserves the source variant automatically; no variant_id override. Optional name (maximum 60 characters after trimming) labels only the interaction; omitted or blank names use the source image name without renaming the image. Costs 9 credits. Returns an asynchronous job receipt. Send once and poll the returned job URL; repeating POST creates and charges a new set. Hosted mascots automatically publish a JSON manifest and nine lossless WebPs. Retrieve them with GET /v1/mascots/{id}/cdn-export after completion. This interaction is independent of Canvas state machines.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.",
      "schema": {
        "type": "string",
        "maxLength": 255
      }
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/CreateInteractionBody"
        }
      }
    }
  },
  "responses": {
    "202": {
      "description": "Nine-direction generation queued",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/InteractionGenerationResponse"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Invalid request",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "402": {
      "description": "Insufficient credits",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "403": {
      "description": "Write access required",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "404": {
      "description": "Mascot or completed source not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "422": {
      "description": "Transparent image required",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "429": {
      "description": "Rate limited",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "500": {
      "description": "Could not queue generation",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    }
  },
  "operationId": "createMascotInteractive",
  "x-masko-api-version": "2026-09-26"
}

GET/v1/mascots/{id}/logos/suggestionsSuggest logo directions and styles

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

variant_idquery

string

refreshquery

string · true, false

Responses

200 Logo ideas

application/json

dataobject · required

Nested fields

prompt_versionnumber · required

cachedboolean · required

descriptionsarray · required

Nested fields

namestring · required

descriptionstring · required

styleobject · nullable

Nested fields

namestring · required

instructionstring · required

preset_idstring

Values: "graphic-app-icon", "cut-paper", "soft-depth", "geometric", "abstract-symbol", "monoline-symbol", "negative-space", "retro-emblem", "hand-drawn"

stylesarray · required

Nested fields

namestring · required

instructionstring · required

preset_idstring

Values: "graphic-app-icon", "cut-paper", "soft-depth", "geometric", "abstract-symbol", "monoline-symbol", "negative-space", "retro-emblem", "hand-drawn"

400 Invalid request

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

402 Insufficient credits

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Write access required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Source or mascot not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Request ID conflict or variant not approved

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

429 Rate limited

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

500 Internal error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

503 Generation unavailable

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Suggestions"
  ],
  "summary": "Suggest logo directions and styles",
  "description": "Five directions, including face portrait and full body, plus three suggested styles. Each direction can include a style. A style can be custom; preset_id is present only when it exactly matches a built-in preset. Returns defaults if generation is unavailable, unless refresh=true, which returns 503. No image credits; does not change the mascot.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": false,
      "name": "variant_id",
      "in": "query"
    },
    {
      "schema": {
        "type": "string",
        "enum": [
          "true",
          "false"
        ]
      },
      "required": false,
      "name": "refresh",
      "in": "query"
    }
  ],
  "responses": {
    "200": {
      "description": "Logo ideas",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "prompt_version": {
                    "type": "number"
                  },
                  "cached": {
                    "type": "boolean"
                  },
                  "descriptions": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string"
                        },
                        "description": {
                          "type": "string"
                        },
                        "style": {
                          "type": "object",
                          "nullable": true,
                          "properties": {
                            "name": {
                              "type": "string"
                            },
                            "instruction": {
                              "type": "string"
                            },
                            "preset_id": {
                              "type": "string",
                              "enum": [
                                "graphic-app-icon",
                                "cut-paper",
                                "soft-depth",
                                "geometric",
                                "abstract-symbol",
                                "monoline-symbol",
                                "negative-space",
                                "retro-emblem",
                                "hand-drawn"
                              ]
                            }
                          },
                          "required": [
                            "name",
                            "instruction"
                          ]
                        }
                      },
                      "required": [
                        "name",
                        "description"
                      ]
                    }
                  },
                  "styles": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string"
                        },
                        "instruction": {
                          "type": "string"
                        },
                        "preset_id": {
                          "type": "string",
                          "enum": [
                            "graphic-app-icon",
                            "cut-paper",
                            "soft-depth",
                            "geometric",
                            "abstract-symbol",
                            "monoline-symbol",
                            "negative-space",
                            "retro-emblem",
                            "hand-drawn"
                          ]
                        }
                      },
                      "required": [
                        "name",
                        "instruction"
                      ]
                    }
                  }
                },
                "required": [
                  "prompt_version",
                  "cached",
                  "descriptions",
                  "styles"
                ]
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Invalid request",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "402": {
      "description": "Insufficient credits",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "403": {
      "description": "Write access required",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "404": {
      "description": "Source or mascot not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "409": {
      "description": "Request ID conflict or variant not approved",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "429": {
      "description": "Rate limited",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "500": {
      "description": "Internal error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "503": {
      "description": "Generation unavailable",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    }
  },
  "operationId": "listMascotLogoSuggestions",
  "x-masko-api-version": "2026-09-26"
}

GET/v1/mascots/{id}/voiceGet the voice

Returns the voice the mascot speaks with in talking animations, or null. A marketplace copy speaks with its creator's voice (source creator). sample_url is a short recording.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

Responses

200 The voice, or null

application/json

dataobject · nullable · required

Nested fields

objectstring · required

Values: "voice"

namestring · required

descriptionstring · required

The words the voice was designed from.

sample_urlstring · uri · nullable · required

A short recording of the voice. Signed; fetch the voice again for a fresh link.

sourcestring · required

Whose voice this is: the mascot's own (original), the variant's own (variant), or the marketplace creator's (creator).

Values: "original", "variant", "creator"

created_atstring · required

400 Invalid request

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Authentication required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 The key lacks permission, or the voice belongs to the Marketplace creator

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Mascot, variant or sample not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 The variant is not approved yet, or the sample expired

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

429 Too many voice requests; retry later

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

502 Masko could not write the ideas or the adjustment; retry

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

503 The voice service is unavailable; retry later

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Voice"
  ],
  "summary": "Get the voice",
  "description": "Returns the voice the mascot speaks with in talking animations, or null. A marketplace copy speaks with its creator's voice (source creator). sample_url is a short recording.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    }
  ],
  "responses": {
    "200": {
      "description": "The voice, or null",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/Voice"
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Invalid request",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "401": {
      "description": "Authentication required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "403": {
      "description": "The key lacks permission, or the voice belongs to the Marketplace creator",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "404": {
      "description": "Mascot, variant or sample not found",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "409": {
      "description": "The variant is not approved yet, or the sample expired",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "429": {
      "description": "Too many voice requests; retry later",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "502": {
      "description": "Masko could not write the ideas or the adjustment; retry",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "503": {
      "description": "The voice service is unavailable; retry later",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  },
  "operationId": "getMascotVoice",
  "x-masko-api-version": "2026-09-26"
}

PUT/v1/mascots/{id}/voiceKeep a voice

Keeps one sample from POST /v1/mascots/{id}/voice/samples as the voice of the mascot. It replaces the voice it had. Samples can be kept for 24 hours. No credit cost.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

Request body (required)

application/json

sample_idstring · uuid · required

A sample from POST .../voice/samples.

namestring

Defaults to "<name>'s voice".

Length: 1 to 80 characters

Responses

200 The kept voice

application/json

dataobject · nullable · required

Nested fields

objectstring · required

Values: "voice"

namestring · required

descriptionstring · required

The words the voice was designed from.

sample_urlstring · uri · nullable · required

A short recording of the voice. Signed; fetch the voice again for a fresh link.

sourcestring · required

Whose voice this is: the mascot's own (original), the variant's own (variant), or the marketplace creator's (creator).

Values: "original", "variant", "creator"

created_atstring · required

400 Invalid request

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Authentication required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 The key lacks permission, or the voice belongs to the Marketplace creator

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Mascot, variant or sample not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 The variant is not approved yet, or the sample expired

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

429 Too many voice requests; retry later

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

502 Masko could not write the ideas or the adjustment; retry

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

503 The voice service is unavailable; retry later

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Voice"
  ],
  "summary": "Keep a voice",
  "description": "Keeps one sample from POST /v1/mascots/{id}/voice/samples as the voice of the mascot. It replaces the voice it had. Samples can be kept for 24 hours. No credit cost.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/KeepVoiceBody"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "The kept voice",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/Voice"
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Invalid request",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "401": {
      "description": "Authentication required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "403": {
      "description": "The key lacks permission, or the voice belongs to the Marketplace creator",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "404": {
      "description": "Mascot, variant or sample not found",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "409": {
      "description": "The variant is not approved yet, or the sample expired",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "429": {
      "description": "Too many voice requests; retry later",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "502": {
      "description": "Masko could not write the ideas or the adjustment; retry",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "503": {
      "description": "The voice service is unavailable; retry later",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  },
  "operationId": "updateMascotVoice",
  "x-masko-api-version": "2026-09-26"
}

DELETE/v1/mascots/{id}/voiceRemove the voice

Removes the mascot's voice. Talking animations already made keep their sound; new ones need a voice.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

Responses

204 Removed

400 Invalid request

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Authentication required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 The key lacks permission, or the voice belongs to the Marketplace creator

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Mascot, variant or sample not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 The variant is not approved yet, or the sample expired

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

429 Too many voice requests; retry later

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

502 Masko could not write the ideas or the adjustment; retry

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

503 The voice service is unavailable; retry later

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Voice"
  ],
  "summary": "Remove the voice",
  "description": "Removes the mascot's voice. Talking animations already made keep their sound; new ones need a voice.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    }
  ],
  "responses": {
    "204": {
      "description": "Removed",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Invalid request",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "401": {
      "description": "Authentication required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "403": {
      "description": "The key lacks permission, or the voice belongs to the Marketplace creator",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "404": {
      "description": "Mascot, variant or sample not found",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "409": {
      "description": "The variant is not approved yet, or the sample expired",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "429": {
      "description": "Too many voice requests; retry later",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "502": {
      "description": "Masko could not write the ideas or the adjustment; retry",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "503": {
      "description": "The voice service is unavailable; retry later",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  },
  "operationId": "deleteMascotVoice",
  "x-masko-api-version": "2026-09-26"
}

GET/v1/mascots/{id}/voice/suggestionsSuggest voices

Returns voice ideas written for the mascot from its references and description. Each description is ready for POST /v1/mascots/{id}/voice/samples. No credit cost.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

refreshquery

Return other ideas than a plain request would.

string · true, false

avoidquery

Comma-separated idea titles not to suggest again.

string

Responses

200 Voice ideas

application/json

dataobject · required

Nested fields

ideasarray · required

Nested fields

titlestring · required

A few words, such as "Cozy and warm".

descriptionstring · required

The full description, ready for POST .../voice/samples.

400 Invalid request

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Authentication required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 The key lacks permission, or the voice belongs to the Marketplace creator

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Mascot, variant or sample not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 The variant is not approved yet, or the sample expired

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

429 Too many voice requests; retry later

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

502 Masko could not write the ideas or the adjustment; retry

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

503 The voice service is unavailable; retry later

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Voice"
  ],
  "summary": "Suggest voices",
  "description": "Returns voice ideas written for the mascot from its references and description. Each description is ready for POST /v1/mascots/{id}/voice/samples. No credit cost.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "schema": {
        "type": "string",
        "enum": [
          "true",
          "false"
        ],
        "description": "Return other ideas than a plain request would."
      },
      "required": false,
      "description": "Return other ideas than a plain request would.",
      "name": "refresh",
      "in": "query"
    },
    {
      "schema": {
        "type": "string",
        "maxLength": 500,
        "description": "Comma-separated idea titles not to suggest again."
      },
      "required": false,
      "description": "Comma-separated idea titles not to suggest again.",
      "name": "avoid",
      "in": "query"
    }
  ],
  "responses": {
    "200": {
      "description": "Voice ideas",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "ideas": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/VoiceIdea"
                    }
                  }
                },
                "required": [
                  "ideas"
                ]
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Invalid request",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "401": {
      "description": "Authentication required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "403": {
      "description": "The key lacks permission, or the voice belongs to the Marketplace creator",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "404": {
      "description": "Mascot, variant or sample not found",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "409": {
      "description": "The variant is not approved yet, or the sample expired",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "429": {
      "description": "Too many voice requests; retry later",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "502": {
      "description": "Masko could not write the ideas or the adjustment; retry",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "503": {
      "description": "The voice service is unavailable; retry later",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  },
  "operationId": "listMascotVoiceSuggestions",
  "x-masko-api-version": "2026-09-26"
}

POST/v1/mascots/{id}/voice/adjustAdjust a voice description

Rewrites a voice description in one direction, such as "Older" or "Slower", and returns what changed plus directions that fit the new text. Without direction, returns only directions. No credit cost.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

Idempotency-Keyheader

string

Request body (required)

application/json

descriptionstring · required

The current voice description.

Length: 1 to 1000 characters

directionstring

A direction such as "Older" or "A little grumpy". Omit it to only get directions for this description.

Length: 0 to 80 characters

Responses

200 The rewritten description

application/json

dataobject · required

Nested fields

descriptionstring · required

The rewritten description.

changesarray · required

Each replaced or added passage. from is empty for added text.

Nested fields

fromstring · required

tostring · required

directionsarray · required

Directions that fit the new description.

Nested fields

string

400 Invalid request

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Authentication required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 The key lacks permission, or the voice belongs to the Marketplace creator

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Mascot, variant or sample not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 The variant is not approved yet, or the sample expired

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

429 Too many voice requests; retry later

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

502 Masko could not write the ideas or the adjustment; retry

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

503 The voice service is unavailable; retry later

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Voice"
  ],
  "summary": "Adjust a voice description",
  "description": "Rewrites a voice description in one direction, such as \"Older\" or \"Slower\", and returns what changed plus directions that fit the new text. Without direction, returns only directions. No credit cost.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.",
      "schema": {
        "type": "string",
        "maxLength": 255
      }
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/AdjustVoiceBody"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "The rewritten description",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/VoiceAdjustment"
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Invalid request",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "401": {
      "description": "Authentication required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "403": {
      "description": "The key lacks permission, or the voice belongs to the Marketplace creator",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "404": {
      "description": "Mascot, variant or sample not found",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "409": {
      "description": "The variant is not approved yet, or the sample expired",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "429": {
      "description": "Too many voice requests; retry later",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "502": {
      "description": "Masko could not write the ideas or the adjustment; retry",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "503": {
      "description": "The voice service is unavailable; retry later",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  },
  "operationId": "adjustMascotVoice",
  "x-masko-api-version": "2026-09-26"
}

POST/v1/mascots/{id}/voice/samplesHear voice samples

Designs three voices from a description, each reading the same line. Costs 1 credit for the three. Keep one with PUT /v1/mascots/{id}/voice within 24 hours.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

Idempotency-Keyheader

string

Request body (required)

application/json

descriptionstring · required

How the voice sounds: age, pitch, pace, energy, texture, mood and accent.

Length: 20 to 1000 characters

sample_linestring

The line the samples read. Lines shorter than 100 characters are extended. Omit it for a line in the mascot's name.

Length: 0 to 500 characters

Responses

201 Three samples

application/json

dataobject · required

Nested fields

samplesarray · required

Nested fields

idstring · uuid · required

Pass it to PUT .../voice to keep this voice.

urlstring · uri · required

durationnumber · nullable · required

sample_linestring · required

cost_creditsnumber · required

expires_atstring · required

Samples not kept by then can no longer be kept.

400 Invalid request

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Authentication required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

402 Not enough credits

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 The key lacks permission, or the voice belongs to the Marketplace creator

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Mascot, variant or sample not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 The variant is not approved yet, or the sample expired

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

429 Too many voice requests; retry later

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

502 Masko could not write the ideas or the adjustment; retry

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

503 The voice service is unavailable; retry later

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Voice"
  ],
  "summary": "Hear voice samples",
  "description": "Designs three voices from a description, each reading the same line. Costs 1 credit for the three. Keep one with PUT /v1/mascots/{id}/voice within 24 hours.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.",
      "schema": {
        "type": "string",
        "maxLength": 255
      }
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/VoiceSamplesBody"
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Three samples",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/VoiceSamples"
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Invalid request",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "401": {
      "description": "Authentication required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "402": {
      "description": "Not enough credits",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "403": {
      "description": "The key lacks permission, or the voice belongs to the Marketplace creator",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "404": {
      "description": "Mascot, variant or sample not found",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "409": {
      "description": "The variant is not approved yet, or the sample expired",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "429": {
      "description": "Too many voice requests; retry later",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "502": {
      "description": "Masko could not write the ideas or the adjustment; retry",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "503": {
      "description": "The voice service is unavailable; retry later",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  },
  "operationId": "createMascotVoiceSample",
  "x-masko-api-version": "2026-09-26"
}

GET/v1/mascots/{id}/variants/{variantId}/voiceGet the voice of a variant

Returns the voice this variant speaks with: its own (source variant), the Original's until it gets one (source original), or null. sample_url is a short recording.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

variantIdpath · required

string

Responses

200 The voice, or null

application/json

dataobject · nullable · required

Nested fields

objectstring · required

Values: "voice"

namestring · required

descriptionstring · required

The words the voice was designed from.

sample_urlstring · uri · nullable · required

A short recording of the voice. Signed; fetch the voice again for a fresh link.

sourcestring · required

Whose voice this is: the mascot's own (original), the variant's own (variant), or the marketplace creator's (creator).

Values: "original", "variant", "creator"

created_atstring · required

400 Invalid request

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Authentication required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 The key lacks permission, or the voice belongs to the Marketplace creator

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Mascot, variant or sample not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 The variant is not approved yet, or the sample expired

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

429 Too many voice requests; retry later

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

502 Masko could not write the ideas or the adjustment; retry

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

503 The voice service is unavailable; retry later

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Voice"
  ],
  "summary": "Get the voice of a variant",
  "description": "Returns the voice this variant speaks with: its own (source variant), the Original's until it gets one (source original), or null. sample_url is a short recording.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "variantId",
      "in": "path"
    }
  ],
  "responses": {
    "200": {
      "description": "The voice, or null",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/Voice"
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Invalid request",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "401": {
      "description": "Authentication required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "403": {
      "description": "The key lacks permission, or the voice belongs to the Marketplace creator",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "404": {
      "description": "Mascot, variant or sample not found",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "409": {
      "description": "The variant is not approved yet, or the sample expired",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "429": {
      "description": "Too many voice requests; retry later",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "502": {
      "description": "Masko could not write the ideas or the adjustment; retry",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "503": {
      "description": "The voice service is unavailable; retry later",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  },
  "operationId": "getMascotVariantVoice",
  "x-masko-api-version": "2026-09-26"
}

PUT/v1/mascots/{id}/variants/{variantId}/voiceKeep a voice of a variant

Keeps one sample from POST /v1/mascots/{id}/variants/{variantId}/voice/samples as the voice of an approved variant. It replaces the voice it had. Samples can be kept for 24 hours. No credit cost.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

variantIdpath · required

string

Request body (required)

application/json

sample_idstring · uuid · required

A sample from POST .../voice/samples.

namestring

Defaults to "<name>'s voice".

Length: 1 to 80 characters

Responses

200 The kept voice

application/json

dataobject · nullable · required

Nested fields

objectstring · required

Values: "voice"

namestring · required

descriptionstring · required

The words the voice was designed from.

sample_urlstring · uri · nullable · required

A short recording of the voice. Signed; fetch the voice again for a fresh link.

sourcestring · required

Whose voice this is: the mascot's own (original), the variant's own (variant), or the marketplace creator's (creator).

Values: "original", "variant", "creator"

created_atstring · required

400 Invalid request

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Authentication required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 The key lacks permission, or the voice belongs to the Marketplace creator

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Mascot, variant or sample not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 The variant is not approved yet, or the sample expired

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

429 Too many voice requests; retry later

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

502 Masko could not write the ideas or the adjustment; retry

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

503 The voice service is unavailable; retry later

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Voice"
  ],
  "summary": "Keep a voice of a variant",
  "description": "Keeps one sample from POST /v1/mascots/{id}/variants/{variantId}/voice/samples as the voice of an approved variant. It replaces the voice it had. Samples can be kept for 24 hours. No credit cost.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "variantId",
      "in": "path"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/KeepVoiceBody"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "The kept voice",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/Voice"
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Invalid request",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "401": {
      "description": "Authentication required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "403": {
      "description": "The key lacks permission, or the voice belongs to the Marketplace creator",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "404": {
      "description": "Mascot, variant or sample not found",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "409": {
      "description": "The variant is not approved yet, or the sample expired",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "429": {
      "description": "Too many voice requests; retry later",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "502": {
      "description": "Masko could not write the ideas or the adjustment; retry",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "503": {
      "description": "The voice service is unavailable; retry later",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  },
  "operationId": "updateMascotVariantVoice",
  "x-masko-api-version": "2026-09-26"
}

DELETE/v1/mascots/{id}/variants/{variantId}/voiceRemove the voice of a variant

Removes the variant's own voice; it speaks with the Original's voice again.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

variantIdpath · required

string

Responses

204 Removed

400 Invalid request

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Authentication required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 The key lacks permission, or the voice belongs to the Marketplace creator

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Mascot, variant or sample not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 The variant is not approved yet, or the sample expired

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

429 Too many voice requests; retry later

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

502 Masko could not write the ideas or the adjustment; retry

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

503 The voice service is unavailable; retry later

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Voice"
  ],
  "summary": "Remove the voice of a variant",
  "description": "Removes the variant's own voice; it speaks with the Original's voice again.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "variantId",
      "in": "path"
    }
  ],
  "responses": {
    "204": {
      "description": "Removed",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Invalid request",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "401": {
      "description": "Authentication required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "403": {
      "description": "The key lacks permission, or the voice belongs to the Marketplace creator",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "404": {
      "description": "Mascot, variant or sample not found",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "409": {
      "description": "The variant is not approved yet, or the sample expired",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "429": {
      "description": "Too many voice requests; retry later",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "502": {
      "description": "Masko could not write the ideas or the adjustment; retry",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "503": {
      "description": "The voice service is unavailable; retry later",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  },
  "operationId": "deleteMascotVariantVoice",
  "x-masko-api-version": "2026-09-26"
}

GET/v1/mascots/{id}/variants/{variantId}/voice/suggestionsSuggest voices of a variant

Returns voice ideas written for an approved variant from its references and description. Each description is ready for POST /v1/mascots/{id}/variants/{variantId}/voice/samples. No credit cost.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

variantIdpath · required

string

refreshquery

Return other ideas than a plain request would.

string · true, false

avoidquery

Comma-separated idea titles not to suggest again.

string

Responses

200 Voice ideas

application/json

dataobject · required

Nested fields

ideasarray · required

Nested fields

titlestring · required

A few words, such as "Cozy and warm".

descriptionstring · required

The full description, ready for POST .../voice/samples.

400 Invalid request

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Authentication required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 The key lacks permission, or the voice belongs to the Marketplace creator

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Mascot, variant or sample not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 The variant is not approved yet, or the sample expired

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

429 Too many voice requests; retry later

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

502 Masko could not write the ideas or the adjustment; retry

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

503 The voice service is unavailable; retry later

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Voice"
  ],
  "summary": "Suggest voices of a variant",
  "description": "Returns voice ideas written for an approved variant from its references and description. Each description is ready for POST /v1/mascots/{id}/variants/{variantId}/voice/samples. No credit cost.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "variantId",
      "in": "path"
    },
    {
      "schema": {
        "type": "string",
        "enum": [
          "true",
          "false"
        ],
        "description": "Return other ideas than a plain request would."
      },
      "required": false,
      "description": "Return other ideas than a plain request would.",
      "name": "refresh",
      "in": "query"
    },
    {
      "schema": {
        "type": "string",
        "maxLength": 500,
        "description": "Comma-separated idea titles not to suggest again."
      },
      "required": false,
      "description": "Comma-separated idea titles not to suggest again.",
      "name": "avoid",
      "in": "query"
    }
  ],
  "responses": {
    "200": {
      "description": "Voice ideas",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "ideas": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/VoiceIdea"
                    }
                  }
                },
                "required": [
                  "ideas"
                ]
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Invalid request",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "401": {
      "description": "Authentication required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "403": {
      "description": "The key lacks permission, or the voice belongs to the Marketplace creator",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "404": {
      "description": "Mascot, variant or sample not found",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "409": {
      "description": "The variant is not approved yet, or the sample expired",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "429": {
      "description": "Too many voice requests; retry later",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "502": {
      "description": "Masko could not write the ideas or the adjustment; retry",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "503": {
      "description": "The voice service is unavailable; retry later",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  },
  "operationId": "listMascotVariantVoiceSuggestions",
  "x-masko-api-version": "2026-09-26"
}

POST/v1/mascots/{id}/variants/{variantId}/voice/adjustAdjust a voice description of a variant

Rewrites a voice description in one direction, such as "Older" or "Slower", and returns what changed plus directions that fit the new text. Without direction, returns only directions. No credit cost.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

variantIdpath · required

string

Idempotency-Keyheader

string

Request body (required)

application/json

descriptionstring · required

The current voice description.

Length: 1 to 1000 characters

directionstring

A direction such as "Older" or "A little grumpy". Omit it to only get directions for this description.

Length: 0 to 80 characters

Responses

200 The rewritten description

application/json

dataobject · required

Nested fields

descriptionstring · required

The rewritten description.

changesarray · required

Each replaced or added passage. from is empty for added text.

Nested fields

fromstring · required

tostring · required

directionsarray · required

Directions that fit the new description.

Nested fields

string

400 Invalid request

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Authentication required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 The key lacks permission, or the voice belongs to the Marketplace creator

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Mascot, variant or sample not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 The variant is not approved yet, or the sample expired

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

429 Too many voice requests; retry later

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

502 Masko could not write the ideas or the adjustment; retry

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

503 The voice service is unavailable; retry later

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Voice"
  ],
  "summary": "Adjust a voice description of a variant",
  "description": "Rewrites a voice description in one direction, such as \"Older\" or \"Slower\", and returns what changed plus directions that fit the new text. Without direction, returns only directions. No credit cost.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "variantId",
      "in": "path"
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.",
      "schema": {
        "type": "string",
        "maxLength": 255
      }
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/AdjustVoiceBody"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "The rewritten description",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/VoiceAdjustment"
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Invalid request",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "401": {
      "description": "Authentication required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "403": {
      "description": "The key lacks permission, or the voice belongs to the Marketplace creator",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "404": {
      "description": "Mascot, variant or sample not found",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "409": {
      "description": "The variant is not approved yet, or the sample expired",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "429": {
      "description": "Too many voice requests; retry later",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "502": {
      "description": "Masko could not write the ideas or the adjustment; retry",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "503": {
      "description": "The voice service is unavailable; retry later",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  },
  "operationId": "adjustMascotVariantVoice",
  "x-masko-api-version": "2026-09-26"
}

POST/v1/mascots/{id}/variants/{variantId}/voice/samplesHear voice samples of a variant

Designs three voices from a description, each reading the same line. Costs 1 credit for the three. Keep one with PUT /v1/mascots/{id}/variants/{variantId}/voice within 24 hours.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

variantIdpath · required

string

Idempotency-Keyheader

string

Request body (required)

application/json

descriptionstring · required

How the voice sounds: age, pitch, pace, energy, texture, mood and accent.

Length: 20 to 1000 characters

sample_linestring

The line the samples read. Lines shorter than 100 characters are extended. Omit it for a line in the mascot's name.

Length: 0 to 500 characters

Responses

201 Three samples

application/json

dataobject · required

Nested fields

samplesarray · required

Nested fields

idstring · uuid · required

Pass it to PUT .../voice to keep this voice.

urlstring · uri · required

durationnumber · nullable · required

sample_linestring · required

cost_creditsnumber · required

expires_atstring · required

Samples not kept by then can no longer be kept.

400 Invalid request

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Authentication required

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

402 Not enough credits

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 The key lacks permission, or the voice belongs to the Marketplace creator

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Mascot, variant or sample not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 The variant is not approved yet, or the sample expired

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

429 Too many voice requests; retry later

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

502 Masko could not write the ideas or the adjustment; retry

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

503 The voice service is unavailable; retry later

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Voice"
  ],
  "summary": "Hear voice samples of a variant",
  "description": "Designs three voices from a description, each reading the same line. Costs 1 credit for the three. Keep one with PUT /v1/mascots/{id}/variants/{variantId}/voice within 24 hours.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "variantId",
      "in": "path"
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.",
      "schema": {
        "type": "string",
        "maxLength": 255
      }
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/VoiceSamplesBody"
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Three samples",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/VoiceSamples"
              }
            },
            "required": [
              "data"
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Invalid request",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "401": {
      "description": "Authentication required",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "402": {
      "description": "Not enough credits",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "403": {
      "description": "The key lacks permission, or the voice belongs to the Marketplace creator",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "404": {
      "description": "Mascot, variant or sample not found",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "409": {
      "description": "The variant is not approved yet, or the sample expired",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "429": {
      "description": "Too many voice requests; retry later",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "502": {
      "description": "Masko could not write the ideas or the adjustment; retry",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "503": {
      "description": "The voice service is unavailable; retry later",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  },
  "operationId": "createMascotVariantVoiceSample",
  "x-masko-api-version": "2026-09-26"
}

GET/v1/mascotsList mascots

Returns all mascots owned by the authenticated user, paginated. A mascot is a single mascot character with its own style, references, and items. No credit cost.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

limitquery

Page size. 1 to 100. Defaults to 50.

number

offsetquery

Number of records to skip. Defaults to 0.

number

cursorquery

Opaque next_cursor from the previous page. Use instead of offset.

string

project_idquery

Filter to this project.

string

typequery

Filter by type, e.g. "mascot".

string

Responses

200 List of mascots

application/json

dataarray · required

Nested fields

objectstring

Resource type. Always "mascot".

Values: "mascot"

idstring · uuid · required

namestring · required

typestring · required

project_idstring · uuid

configobject

Nested fields

promptstring · required

reference_asset_idsarray · required

Nested fields

string

style_cardobject · nullable · required

caution_listarray · required

Nested fields

string

is_publishedboolean

slugstring · nullable

user_prefixstring · nullable

room_for_movementboolean

cdn_statusarray

Nested fields

asset_idstring · uuid · required

item_namestring · nullable · required

typestring · required

cdn_urlstring · uri · required

statusstring · required

file_sizenumber · nullable · required

created_atstring · required

updated_atstring · required

metaobject · required

Nested fields

paginationobject

Nested fields

totalinteger · required

Range: 0 to unbounded

limitinteger · required

Range: 0 to unbounded

offsetinteger · required

Range: 0 to unbounded

has_moreboolean · required

next_cursorstring · nullable

Pass as the cursor query parameter to get the next page. Null on the last page.

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Mascots"
  ],
  "summary": "List mascots",
  "description": "Returns all mascots owned by the authenticated user, paginated. A mascot is a single mascot character with its own style, references, and items. No credit cost.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "number",
        "minimum": 1,
        "maximum": 100,
        "default": 50,
        "description": "Page size. 1 to 100. Defaults to 50."
      },
      "required": false,
      "description": "Page size. 1 to 100. Defaults to 50.",
      "name": "limit",
      "in": "query"
    },
    {
      "schema": {
        "type": "number",
        "nullable": true,
        "minimum": 0,
        "default": 0,
        "description": "Number of records to skip. Defaults to 0."
      },
      "required": false,
      "description": "Number of records to skip. Defaults to 0.",
      "name": "offset",
      "in": "query"
    },
    {
      "schema": {
        "type": "string",
        "description": "Opaque next_cursor from the previous page. Use instead of offset."
      },
      "required": false,
      "description": "Opaque next_cursor from the previous page. Use instead of offset.",
      "name": "cursor",
      "in": "query"
    },
    {
      "schema": {
        "type": "string",
        "format": "uuid",
        "description": "Filter to this project."
      },
      "required": false,
      "description": "Filter to this project.",
      "name": "project_id",
      "in": "query"
    },
    {
      "schema": {
        "type": "string",
        "description": "Filter by type, e.g. \"mascot\"."
      },
      "required": false,
      "description": "Filter by type, e.g. \"mascot\".",
      "name": "type",
      "in": "query"
    }
  ],
  "responses": {
    "200": {
      "description": "List of mascots",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CollectionListResponse"
          },
          "example": {
            "data": [
              {
                "id": "f9503022-a991-46ea-bf8c-d628c921b6b0",
                "name": "v1-api-test-cat-1776591403",
                "type": "mascot",
                "project_id": "04dae799-dd9a-4296-ba86-9e3913c2f8d1",
                "project_name": "test",
                "is_published": true,
                "public_slug": "v1-api-test-cat-1776591403-rmau1uyd",
                "user_prefix": "fda8417d",
                "created_at": "2026-04-19T09:36:43.46139+00:00"
              }
            ],
            "meta": {
              "pagination": {
                "total": 6,
                "limit": 5,
                "offset": 0,
                "has_more": true
              }
            }
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    }
  },
  "operationId": "listMascots",
  "x-masko-api-version": "2026-09-26"
}

POST/v1/mascotsCreate a mascot

This is the primary way to create a mascot. In the API the resource is called mascot - today one mascot holds one mascot so the terms are interchangeable. Recommended input is reference images (reference_image_urls or reference_asset_ids from POST /v1/upload) - one or more images of the character. The references ARE the mascot; you do not need to describe it in prompt. Use context to add things the image cannot express: personality, consistency rules ("always wears red sneakers"), forbidden variants ("never without the hat"), brand tone. The mascot is assigned to a project and gets a public CDN slug. Creation with existing references or name/context only is free. Providing prompt without references generates one reference for 1 credit. Failed generation, storage or persistence triggers a refund, with background retries if immediate repayment fails. Use Idempotency-Key to replay a request without generating or charging again. Future /generate calls use the style automatically extracted from the references.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

Idempotency-Keyheader

string

Request body (required)

Request body

application/json

project_idstring · uuid · required

Project to create the mascot in. List projects via GET /v1/projects.

namestring

Display name. Defaults to a generated name if omitted.

promptstring

contextstring

typestring

Mascot type. Defaults to "mascot".

Default: "mascot"

stylestring

Style ID or name. List styles via GET /v1/styles.

design_touchesarray

Items: 0 to 22

Nested fields

reference_image_urlsarray

Nested fields

string

reference_asset_idsarray

Nested fields

string

settingsobject

Mascot settings. cdn_enabled: whether new assets auto-publish to the CDN. animation_sizes: up to 2 smaller pixel widths to auto-generate variants for, e.g. [480, 240]. Every animation already gets its 720 px files, so 720 and larger values are ignored. Common values: 480, 360, 240, 128.

Nested fields

cdn_enabledboolean

Default: true

animation_sizesarray

Nested fields

number

Responses

201 Created mascot

application/json

dataobject · required

Nested fields

objectstring

Resource type. Always "mascot".

Values: "mascot"

idstring · uuid · required

namestring · required

typestring · required

project_idstring · uuid

configobject

Nested fields

promptstring · required

reference_asset_idsarray · required

Nested fields

string

style_cardobject · nullable · required

caution_listarray · required

Nested fields

string

is_publishedboolean

slugstring · nullable

user_prefixstring · nullable

room_for_movementboolean

cdn_statusarray

Nested fields

asset_idstring · uuid · required

item_namestring · nullable · required

typestring · required

cdn_urlstring · uri · required

statusstring · required

file_sizenumber · nullable · required

created_atstring · required

updated_atstring · required

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Mascots"
  ],
  "summary": "Create a mascot",
  "description": "This is the primary way to create a mascot. In the API the resource is called `mascot` - today one mascot holds one mascot so the terms are interchangeable. Recommended input is reference images (`reference_image_urls` or `reference_asset_ids` from POST /v1/upload) - one or more images of the character. The references ARE the mascot; you do not need to describe it in `prompt`. Use `context` to add things the image cannot express: personality, consistency rules (\"always wears red sneakers\"), forbidden variants (\"never without the hat\"), brand tone. The mascot is assigned to a project and gets a public CDN slug. Creation with existing references or name/context only is free. Providing prompt without references generates one reference for 1 credit. Failed generation, storage or persistence triggers a refund, with background retries if immediate repayment fails. Use Idempotency-Key to replay a request without generating or charging again. Future /generate calls use the style automatically extracted from the references.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "requestBody": {
    "required": true,
    "description": "Request body",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/StudioCreateMascotBody"
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Created mascot",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CollectionResponse"
          },
          "example": {
            "data": {
              "id": "f9503022-a991-46ea-bf8c-d628c921b6b0",
              "name": "v1-api-test-cat-1776591403",
              "slug": "v1-api-test-cat-1776591403-rmau1uyd",
              "type": "mascot",
              "reference_asset_ids": [
                "e906ebb5-deb1-4010-82f9-f0182a3812e0",
                "5114bec3-b92a-4917-8675-84fce713d3cf"
              ],
              "settings": {
                "cdn_enabled": true,
                "animation_sizes": []
              }
            }
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    }
  },
  "operationId": "createMascot",
  "parameters": [
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.",
      "schema": {
        "type": "string",
        "maxLength": 255
      }
    }
  ],
  "x-masko-api-version": "2026-09-26"
}

GET/v1/mascots/{id}Get mascot details

Returns the full mascot record including config (prompt, reference_asset_ids, style_card, caution_list) and cdn_status. Returns 404 if the mascot does not exist or is not owned by the caller.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

Responses

200 Mascot details with cdn_status

application/json

dataobject · required

Nested fields

objectstring

Resource type. Always "mascot".

Values: "mascot"

idstring · uuid · required

namestring · required

typestring · required

project_idstring · uuid

configobject

Nested fields

promptstring · required

reference_asset_idsarray · required

Nested fields

string

style_cardobject · nullable · required

caution_listarray · required

Nested fields

string

is_publishedboolean

slugstring · nullable

user_prefixstring · nullable

room_for_movementboolean

cdn_statusarray

Nested fields

asset_idstring · uuid · required

item_namestring · nullable · required

typestring · required

cdn_urlstring · uri · required

statusstring · required

file_sizenumber · nullable · required

created_atstring · required

updated_atstring · required

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Mascots"
  ],
  "summary": "Get mascot details",
  "description": "Returns the full mascot record including config (prompt, reference_asset_ids, style_card, caution_list) and cdn_status. Returns 404 if the mascot does not exist or is not owned by the caller.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    }
  ],
  "responses": {
    "200": {
      "description": "Mascot details with cdn_status",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CollectionResponse"
          },
          "example": {
            "data": {
              "id": "f9503022-a991-46ea-bf8c-d628c921b6b0",
              "name": "v1-api-test-cat-1776591403",
              "type": "mascot",
              "project_id": "04dae799-dd9a-4296-ba86-9e3913c2f8d1",
              "config": {
                "prompt": "terracotta clay cat mascot with big eyes and speckled texture",
                "reference_asset_ids": [
                  "e906ebb5-deb1-4010-82f9-f0182a3812e0",
                  "5114bec3-b92a-4917-8675-84fce713d3cf"
                ],
                "style_card": null,
                "caution_list": []
              },
              "is_published": true,
              "slug": "v1-api-test-cat-1776591403-rmau1uyd",
              "user_prefix": "fda8417d",
              "cdn_status": [],
              "created_at": "2026-04-19T09:36:43.46139+00:00",
              "updated_at": "2026-04-19T09:36:46.966862+00:00"
            }
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    }
  },
  "operationId": "getMascot",
  "x-masko-api-version": "2026-09-26"
}

PATCH/v1/mascots/{id}Update mascot metadata

Updates a mascot name, prompt, or public slug. Returns { updated: true }. Returns 404 if not found or not owned by the caller. No credit cost.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

Request body (required)

Request body

application/json

namestring

New display name.

contextstring

Updated brand or product context.

slugstring

CDN slug for this mascot. Used in the public URL path: https://assets.masko.ai/:user_prefix/:slug/... Globally unique across all mascots. Normalized server-side: lowercased, non-alphanumeric stripped (hyphens kept), trimmed. After normalization must be 2 to 50 characters. Returns 409 if taken.

Length: 2 to 50 characters

configobject

Raw config object merged into existing config. Advanced use only: prefer dedicated endpoints /references and /settings; set slug with PATCH /v1/collections/:id.

room_for_movementboolean

Responses

200 Updated mascot

application/json

dataobject · required

Nested fields

updatedboolean · required

slugstring

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Mascots"
  ],
  "summary": "Update mascot metadata",
  "description": "Updates a mascot name, prompt, or public slug. Returns { updated: true }. Returns 404 if not found or not owned by the caller. No credit cost.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    }
  ],
  "requestBody": {
    "required": true,
    "description": "Request body",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/StudioUpdateMascotBody"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Updated mascot",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/UpdatedFlagResponse"
          },
          "example": {
            "data": {
              "updated": true
            }
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    }
  },
  "operationId": "updateMascot",
  "x-masko-api-version": "2026-09-26"
}

GET/v1/mascots/{id}/itemsList items in a mascot

Returns paginated items in a mascot. An item groups related assets (e.g. "wave" item may have an image, a transparent image, and animation variants). Filter by type to narrow results. No credit cost.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

limitquery

Page size. 1 to 100. Defaults to 50.

number

offsetquery

Number of records to skip. Defaults to 0.

number

cursorquery

Opaque next_cursor from the previous page. Use instead of offset.

string

typequery

string

Responses

200 List of items

application/json

dataarray · required

Nested fields

objectstring

Resource type. Always "item".

Values: "item"

idstring · uuid · required

namestring · required

typestring · required

promptstring · required

public_slugstring · nullable · required

metadataobject · nullable

created_atstring · required

metaobject · required

Nested fields

paginationobject

Nested fields

totalinteger · required

Range: 0 to unbounded

limitinteger · required

Range: 0 to unbounded

offsetinteger · required

Range: 0 to unbounded

has_moreboolean · required

next_cursorstring · nullable

Pass as the cursor query parameter to get the next page. Null on the last page.

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Items"
  ],
  "summary": "List items in a mascot",
  "description": "Returns paginated items in a mascot. An item groups related assets (e.g. \"wave\" item may have an image, a transparent image, and animation variants). Filter by `type` to narrow results. No credit cost.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "schema": {
        "type": "number",
        "minimum": 1,
        "maximum": 100,
        "default": 50,
        "description": "Page size. 1 to 100. Defaults to 50."
      },
      "required": false,
      "description": "Page size. 1 to 100. Defaults to 50.",
      "name": "limit",
      "in": "query"
    },
    {
      "schema": {
        "type": "number",
        "nullable": true,
        "minimum": 0,
        "default": 0,
        "description": "Number of records to skip. Defaults to 0."
      },
      "required": false,
      "description": "Number of records to skip. Defaults to 0.",
      "name": "offset",
      "in": "query"
    },
    {
      "schema": {
        "type": "string",
        "description": "Opaque next_cursor from the previous page. Use instead of offset."
      },
      "required": false,
      "description": "Opaque next_cursor from the previous page. Use instead of offset.",
      "name": "cursor",
      "in": "query"
    },
    {
      "schema": {
        "type": "string"
      },
      "required": false,
      "name": "type",
      "in": "query"
    }
  ],
  "responses": {
    "200": {
      "description": "List of items",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ItemListResponse"
          },
          "example": {
            "data": [],
            "meta": {
              "pagination": {
                "total": 0,
                "limit": 5,
                "offset": 0,
                "has_more": false
              }
            }
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    }
  },
  "operationId": "listMascotItems",
  "x-masko-api-version": "2026-09-26"
}

GET/v1/mascots/{id}/items/{itemId}Get item details

Returns the item record with all its generated assets (images, animations, logos). Returns 404 if the item does not exist or is not in the given mascot. No credit cost.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

itemIdpath · required

string

Responses

200 Item details with assets

application/json

dataobject · required

Nested fields

Item

objectstring

Resource type. Always "item".

Values: "item"

idstring · uuid · required

namestring · required

typestring · required

promptstring · required

public_slugstring · nullable · required

metadataobject · nullable

created_atstring · required

Option 2

assetsarray · required

Nested fields

objectstring

Resource type. Always "asset".

Values: "asset"

idstring · uuid · required

typestring · required

Values: "interactive", "interactive_frame", "image", "transparent_image", "sticker_image", "svg", "video", "webm", "hevc", "stacked_video", "stacked_video_av1", "logo", "audio", "transcript"

statusstring · required

metadataobject · nullable

Media dimensions, format and public asset context. Internal generation execution details are omitted.

item_idstring · uuid · nullable · required

mascot_idstring · uuid · nullable

file_urlstring · uri · nullable · required

cdn_urlstring · uri · nullable · required

file_sizeinteger · nullable

Size of the file in bytes; null until the file is completed, or when it cannot be read.

is_archivedboolean

archived_atstring · nullable

created_atstring · required

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Items"
  ],
  "summary": "Get item details",
  "description": "Returns the item record with all its generated assets (images, animations, logos). Returns 404 if the item does not exist or is not in the given mascot. No credit cost.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "itemId",
      "in": "path"
    }
  ],
  "responses": {
    "200": {
      "description": "Item details with assets",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/StudioItemResponse"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    }
  },
  "operationId": "getMascotItem",
  "x-masko-api-version": "2026-09-26"
}

PATCH/v1/mascots/{id}/items/{itemId}Update item name or prompt

Updates the item name (used to derive the public slug) and/or the prompt. Does not re-generate assets. No credit cost.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

itemIdpath · required

string

Request body (required)

Request body

application/json

namestring

Length: 1 to unbounded characters

promptstring

Responses

200 Updated item

application/json

dataobject · required

Nested fields

Item

objectstring

Resource type. Always "item".

Values: "item"

idstring · uuid · required

namestring · required

typestring · required

promptstring · required

public_slugstring · nullable · required

metadataobject · nullable

created_atstring · required

Option 2

assetsarray · required

Nested fields

objectstring

Resource type. Always "asset".

Values: "asset"

idstring · uuid · required

typestring · required

Values: "interactive", "interactive_frame", "image", "transparent_image", "sticker_image", "svg", "video", "webm", "hevc", "stacked_video", "stacked_video_av1", "logo", "audio", "transcript"

statusstring · required

metadataobject · nullable

Media dimensions, format and public asset context. Internal generation execution details are omitted.

item_idstring · uuid · nullable · required

mascot_idstring · uuid · nullable

file_urlstring · uri · nullable · required

cdn_urlstring · uri · nullable · required

file_sizeinteger · nullable

Size of the file in bytes; null until the file is completed, or when it cannot be read.

is_archivedboolean

archived_atstring · nullable

created_atstring · required

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Items"
  ],
  "summary": "Update item name or prompt",
  "description": "Updates the item name (used to derive the public slug) and/or the prompt. Does not re-generate assets. No credit cost.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "itemId",
      "in": "path"
    }
  ],
  "requestBody": {
    "required": true,
    "description": "Request body",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/UpdateItemBody"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Updated item",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/StudioItemResponse"
          },
          "example": {
            "data": {
              "id": "e8ca0d1b-b445-46f6-862f-26b26ac2c6ff",
              "name": "sitting-calmly",
              "prompt": "sitting on ground with closed eyes peacefully",
              "public_slug": "sitting",
              "created_at": "2026-04-19T09:44:26.659167+00:00"
            }
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    }
  },
  "operationId": "updateMascotItem",
  "x-masko-api-version": "2026-09-26"
}

DELETE/v1/mascots/{id}/items/{itemId}Archive an item

Soft-deletes (archives) the item and its assets. Files are retained but filtered from reads. Returns 204 on success. No credit cost.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

itemIdpath · required

string

Responses

204 Archived

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Items"
  ],
  "summary": "Archive an item",
  "description": "Soft-deletes (archives) the item and its assets. Files are retained but filtered from reads. Returns 204 on success. No credit cost.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "itemId",
      "in": "path"
    }
  ],
  "responses": {
    "204": {
      "description": "Archived",
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    }
  },
  "operationId": "deleteMascotItem",
  "x-masko-api-version": "2026-09-26"
}

GET/v1/mascots/{id}/assetsList assets in a mascot

Returns paginated assets in a mascot (images, videos, transparent variants). Each asset has a signed file_url (1-hour expiry) and a cdn_url when published. Filter by type or item_id. Set include_file_urls=false for faster metadata-only listings. No credit cost.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

limitquery

Page size. 1 to 100. Defaults to 50.

number

offsetquery

Number of records to skip. Defaults to 0.

number

cursorquery

Opaque next_cursor from the previous page. Use instead of offset.

string

typequery

string

item_idquery

string

include_file_urlsquery

Whether to include signed file_url values. Defaults to true. Set false for faster metadata-only listings.

string · true, false

Responses

200 List of assets

application/json

dataarray · required

Nested fields

objectstring

Resource type. Always "asset".

Values: "asset"

idstring · uuid · required

typestring · required

Values: "interactive", "interactive_frame", "image", "transparent_image", "sticker_image", "svg", "video", "webm", "hevc", "stacked_video", "stacked_video_av1", "logo", "audio", "transcript"

statusstring · required

metadataobject · nullable

Media dimensions, format and public asset context. Internal generation execution details are omitted.

item_idstring · uuid · nullable · required

mascot_idstring · uuid · nullable

file_urlstring · uri · nullable · required

cdn_urlstring · uri · nullable · required

file_sizeinteger · nullable

Size of the file in bytes; null until the file is completed, or when it cannot be read.

is_archivedboolean

archived_atstring · nullable

created_atstring · required

metaobject · required

Nested fields

paginationobject

Nested fields

totalinteger · required

Range: 0 to unbounded

limitinteger · required

Range: 0 to unbounded

offsetinteger · required

Range: 0 to unbounded

has_moreboolean · required

next_cursorstring · nullable

Pass as the cursor query parameter to get the next page. Null on the last page.

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Assets"
  ],
  "summary": "List assets in a mascot",
  "description": "Returns paginated assets in a mascot (images, videos, transparent variants). Each asset has a signed `file_url` (1-hour expiry) and a `cdn_url` when published. Filter by `type` or `item_id`. Set `include_file_urls=false` for faster metadata-only listings. No credit cost.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "schema": {
        "type": "number",
        "minimum": 1,
        "maximum": 100,
        "default": 50,
        "description": "Page size. 1 to 100. Defaults to 50."
      },
      "required": false,
      "description": "Page size. 1 to 100. Defaults to 50.",
      "name": "limit",
      "in": "query"
    },
    {
      "schema": {
        "type": "number",
        "nullable": true,
        "minimum": 0,
        "default": 0,
        "description": "Number of records to skip. Defaults to 0."
      },
      "required": false,
      "description": "Number of records to skip. Defaults to 0.",
      "name": "offset",
      "in": "query"
    },
    {
      "schema": {
        "type": "string",
        "description": "Opaque next_cursor from the previous page. Use instead of offset."
      },
      "required": false,
      "description": "Opaque next_cursor from the previous page. Use instead of offset.",
      "name": "cursor",
      "in": "query"
    },
    {
      "schema": {
        "type": "string"
      },
      "required": false,
      "name": "type",
      "in": "query"
    },
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": false,
      "name": "item_id",
      "in": "query"
    },
    {
      "schema": {
        "type": "string",
        "enum": [
          "true",
          "false"
        ],
        "description": "Whether to include signed file_url values. Defaults to true. Set false for faster metadata-only listings."
      },
      "required": false,
      "description": "Whether to include signed file_url values. Defaults to true. Set false for faster metadata-only listings.",
      "name": "include_file_urls",
      "in": "query"
    }
  ],
  "responses": {
    "200": {
      "description": "List of assets",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/StudioAssetListResponse"
          },
          "example": {
            "data": [
              {
                "id": "5114bec3-b92a-4917-8675-84fce713d3cf",
                "type": "image",
                "status": "completed",
                "metadata": {},
                "item_id": null,
                "file_url": "https://storage.googleapis.com/masco-media/references/.../f4bdfb19.png?GoogleAccessId=...&Expires=...&Signature=...",
                "cdn_url": null,
                "created_at": "2026-04-19T09:36:46.95543+00:00"
              }
            ],
            "meta": {
              "pagination": {
                "total": 2,
                "limit": 5,
                "offset": 0,
                "has_more": false
              }
            }
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    }
  },
  "operationId": "listMascotAssets",
  "x-masko-api-version": "2026-09-26"
}

GET/v1/mascots/{id}/cdn-exportExport published CDN links

Returns the same clean hosted-link JSON shown in the mascot page Get Links export modal. This endpoint is built from published CDN assets, not raw item types, so pose/image items with attached video loops are included. Includes image sticker URL arrays, animated_stickers grouped by sticker ID with telegram, whatsapp, wechat and discord URL keys in formats, and complete cursor-follower interactions with nine WebP frame URLs and a JSON manifest URL. Only completed, non-archived hosted assets are included. Create cursor followers with POST /v1/mascots/{id}/interactive. Use the raw items and assets endpoints for IDs, prompts, metadata, and status checks. Returns 409 cdn_export_not_ready while asset hosting is off (turn it on with POST /v1/mascots/{id}/publish after the owner agrees) or before any file is hosted. No credit cost.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

Responses

200 Mascot CDN export JSON

application/json

mascotstring · required

itemsarray · required

Nested fields

namestring · required

svgstring · uri

imagestring · uri

transparent_imagestring · uri

animationsarray

Nested fields

object

logosobject

stickersarray

Nested fields

string

animated_stickersarray

Nested fields

idstring · uuid · required

source_asset_idstring · uuid · required

formatsobject · required

Nested fields

telegramstring · uri

whatsappstring · uri

wechatstring · uri

discordstring · uri

interactionsarray

Nested fields

versionnumber · required

Values: 1

idstring · uuid · required

namestring · required

kindstring · required

Values: "cursor-follower"

widthnumber · required

Values: 1024

heightnumber · required

Values: 1024

framesobject · required

Nested fields

up-leftstring · uri · required

upstring · uri · required

up-rightstring · uri · required

leftstring · uri · required

centerstring · uri · required

rightstring · uri · required

down-leftstring · uri · required

downstring · uri · required

down-rightstring · uri · required

manifest_urlstring · uri · required

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 CDN export is not ready

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Mascots"
  ],
  "summary": "Export published CDN links",
  "description": "Returns the same clean hosted-link JSON shown in the mascot page Get Links export modal. This endpoint is built from published CDN assets, not raw item types, so pose/image items with attached video loops are included. Includes image sticker URL arrays, animated_stickers grouped by sticker ID with telegram, whatsapp, wechat and discord URL keys in formats, and complete cursor-follower interactions with nine WebP frame URLs and a JSON manifest URL. Only completed, non-archived hosted assets are included. Create cursor followers with POST /v1/mascots/{id}/interactive. Use the raw items and assets endpoints for IDs, prompts, metadata, and status checks. Returns 409 cdn_export_not_ready while asset hosting is off (turn it on with POST /v1/mascots/{id}/publish after the owner agrees) or before any file is hosted. No credit cost.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    }
  ],
  "responses": {
    "200": {
      "description": "Mascot CDN export JSON",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/StudioCdnExportResponse"
          },
          "example": {
            "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",
                    "transparent_video_android_360": "https://assets.masko.ai/fda8417d/fox-mascot/card-sit-360.mp4"
                  }
                ],
                "animated_stickers": [
                  {
                    "id": "22222222-2222-4222-8222-222222222222",
                    "source_asset_id": "33333333-3333-4333-8333-333333333333",
                    "formats": {
                      "telegram": "https://assets.masko.ai/fda8417d/fox-mascot/card-sit-sticker.webm",
                      "whatsapp": "https://assets.masko.ai/fda8417d/fox-mascot/card-sit-sticker.webp",
                      "wechat": "https://assets.masko.ai/fda8417d/fox-mascot/card-sit-sticker.gif",
                      "discord": "https://assets.masko.ai/fda8417d/fox-mascot/card-sit-sticker.png"
                    }
                  }
                ]
              }
            ]
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "409": {
      "description": "CDN export is not ready",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    }
  },
  "operationId": "getMascotCdnExport",
  "x-masko-api-version": "2026-09-26"
}

POST/v1/mascots/{id}/publishTurn on asset hosting

Turns on asset hosting for this mascot, the same switch as Get Links in Studio. Every finished image and video gets a permanent public URL on assets.masko.ai, and files finished later are hosted automatically. Anyone with a URL can open the file, so confirm with the mascot owner before calling it. Mascots created with the API start with hosting on (settings.cdn_enabled); mascots made in Studio or through the MCP server start with it off. Calling it again on a hosted mascot changes nothing and returns changed: false with the current URLs; pass force: true to host missing finished files or refresh them. Changing the slug of a hosted mascot requires force: true, otherwise 409. Returns 400 when the mascot has no finished file yet. Afterwards GET /v1/mascots/{id}/cdn-export lists every hosted link. No generation credits; hosting is free up to 50,000 views a month, then 1 credit per 1,000 views.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

Idempotency-Keyheader

string

Request body

Optional. Send {} or no body to use the current slug.

application/json

slugstring

Optional CDN slug. If omitted, the existing slug or generated mascot slug is used.

Length: 2 to 50 characters

forceboolean

Republish even if CDN rows already exist. Use this to backfill or refresh CDN assets after a partial publish.

Default: false

Responses

200 Asset hosting is on

application/json

dataobject · required

Nested fields

successboolean · required

mascot_idstring · uuid · required

public_slugstring · required

user_prefixstring · nullable · required

cdn_asset_countinteger · required

Range: 0 to unbounded

publishedboolean · required

Values: true

changedboolean · required

False when the mascot was already hosted and nothing was published.

public_urlsobject · nullable · required

Hosted URLs by item slug, then by format key (webm, hevc, image, transparent_image, size variants such as webm_360).

Nested fields

basestring · required

itemsobject · required

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Mascots"
  ],
  "summary": "Turn on asset hosting",
  "description": "Turns on asset hosting for this mascot, the same switch as Get Links in Studio. Every finished image and video gets a permanent public URL on assets.masko.ai, and files finished later are hosted automatically. Anyone with a URL can open the file, so confirm with the mascot owner before calling it. Mascots created with the API start with hosting on (settings.cdn_enabled); mascots made in Studio or through the MCP server start with it off. Calling it again on a hosted mascot changes nothing and returns changed: false with the current URLs; pass force: true to host missing finished files or refresh them. Changing the slug of a hosted mascot requires force: true, otherwise 409. Returns 400 when the mascot has no finished file yet. Afterwards GET /v1/mascots/{id}/cdn-export lists every hosted link. No generation credits; hosting is free up to 50,000 views a month, then 1 credit per 1,000 views.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.",
      "schema": {
        "type": "string",
        "maxLength": 255
      }
    }
  ],
  "requestBody": {
    "required": false,
    "description": "Optional. Send {} or no body to use the current slug.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/StudioPublishMascotBody"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Asset hosting is on",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/StudioPublishMascotResponse"
          },
          "example": {
            "data": {
              "success": true,
              "mascot_id": "f9503022-a991-46ea-bf8c-d628c921b6b0",
              "public_slug": "fox-mascot-f950",
              "user_prefix": "fda841",
              "cdn_asset_count": 12,
              "published": true,
              "changed": true,
              "public_urls": {
                "base": "https://assets.masko.ai/fda841/fox-mascot-f950",
                "items": {
                  "card-sit": {
                    "image": "https://assets.masko.ai/fda841/fox-mascot-f950/card-sit.png",
                    "webm": "https://assets.masko.ai/fda841/fox-mascot-f950/card-sit.webm",
                    "hevc": "https://assets.masko.ai/fda841/fox-mascot-f950/card-sit.mov"
                  }
                }
              }
            }
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    }
  },
  "operationId": "publishMascot",
  "x-masko-api-version": "2026-09-26"
}

POST/v1/mascots/{id}/referencesAdd a reference image

Adds an image as a mascot-scoped style reference (up to 6 references). Pass either url to download and store a new reference, or asset_id to copy an existing uploaded/generated image into this mascot when needed. The returned reference_asset_ids are always mascot-scoped assets that the app can display and future generations can use. Invalidates the cached style_card, which will be re-extracted on next generation. No credit cost.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

Idempotency-Keyheader

string

Request body (required)

Request body

application/json

asset_idstring · uuid

Asset ID of an existing uploaded or generated image. If the asset is not already scoped to this mascot, the API creates a mascot-scoped reference copy and stores that copied asset ID in reference_asset_ids.

urlstring · uri

Responses

201 Reference added

application/json

dataobject · required

Nested fields

reference_asset_idsarray · required

Nested fields

string

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "References"
  ],
  "summary": "Add a reference image",
  "description": "Adds an image as a mascot-scoped style reference (up to 6 references). Pass either `url` to download and store a new reference, or `asset_id` to copy an existing uploaded/generated image into this mascot when needed. The returned `reference_asset_ids` are always mascot-scoped assets that the app can display and future generations can use. Invalidates the cached style_card, which will be re-extracted on next generation. No credit cost.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.",
      "schema": {
        "type": "string",
        "maxLength": 255
      }
    }
  ],
  "requestBody": {
    "required": true,
    "description": "Request body",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/StudioAddReferenceBody"
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Reference added",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ReferenceResponse"
          },
          "example": {
            "data": {
              "reference_asset_ids": [
                "e906ebb5-deb1-4010-82f9-f0182a3812e0",
                "5114bec3-b92a-4917-8675-84fce713d3cf",
                "b357dfe9-92ab-4696-beb3-4f36779808f2"
              ]
            }
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    }
  },
  "operationId": "createMascotReference",
  "x-masko-api-version": "2026-09-26"
}

DELETE/v1/mascots/{id}/references/{assetId}Remove a reference image

Removes an asset from the mascot reference list. Returns the updated reference_asset_ids array. Invalidates the cached style_card. No credit cost.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

assetIdpath · required

string

Responses

200 Reference removed

application/json

dataobject · required

Nested fields

reference_asset_idsarray · required

Nested fields

string

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "References"
  ],
  "summary": "Remove a reference image",
  "description": "Removes an asset from the mascot reference list. Returns the updated `reference_asset_ids` array. Invalidates the cached style_card. No credit cost.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "assetId",
      "in": "path"
    }
  ],
  "responses": {
    "200": {
      "description": "Reference removed",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ReferenceResponse"
          },
          "example": {
            "data": {
              "reference_asset_ids": [
                "e906ebb5-deb1-4010-82f9-f0182a3812e0",
                "5114bec3-b92a-4917-8675-84fce713d3cf"
              ]
            }
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    }
  },
  "operationId": "deleteMascotReference",
  "x-masko-api-version": "2026-09-26"
}

POST/v1/mascots/{id}/generateGenerate image or animation

Starts an async generation job. Returns 202 with data.job_id - poll via GET /v1/jobs/{id} (or pass ?wait=true for long-polling). Cost by type: image=1, animation=2/sec with animation_model=standard (2–15s) or 6/sec with animation_model=premium (4–30s), default 5s for either choice (+1 if no source image); omitting animation_model preserves legacy 5/sec, 4–10s, default 4s, logo=5, edit=1 for images, background=3, reverse=0. For type: animation, you can skip providing a source image: pass only animation_prompt (and optionally image_prompt) and the system generates a fresh source image first, then animates it. To animate an uploaded image directly, pass its POST /v1/upload asset_id as source_image_asset_id with type=animation. The upload is imported into the mascot without changing references; no image-generation credits are charged. Existing mascot assets preserve their saved context. Before video generation, non-square starting and ending images are center-cropped to square; square images are reused unchanged. Optional source_image_crop and end_image_crop specify integer x, y, width and height in pixels after image orientation. Cropped copies preserve the originals and incur no extra credits. Invalid crops return 400 before charging. If you have an existing item, pass item_id to animate/edit its current image. For image generation and image edits, pass optional visual_references for one-time pose, expression, motion, prop, style, or scene cues; these references do not become mascot mascot references. Backgrounds use this endpoint with type: "background": an empty place in the mascot's own style, with no mascot in it and a spot where its animation plays on top. place sets the shape (phone_screen, phone_header, square, web_hero, banner) and description optionally describes the place; optional source_asset_id selects the mascot picture used as the style sample. To change a background, pass its source_image_asset_id with another place, edit_instructions, or both; the two source fields are mutually exclusive. type: "scene" was replaced by type: "background" and returns 400. Talking animations: pass speech with type: animation and the mascot says the line in its voice (see the Voice endpoints). The length follows the speech, 5 seconds to 5 minutes at 2 credits per second; the receipt charges the longest the line could need and unused seconds are refunded once the voice is recorded. Talking adds audio (MP3) and transcript (JSON) assets. With dry_run: true it returns 200 with the estimate instead. Returns 409 with details.reason voice_required when the mascot has no voice yet. Returns 402 if credits are insufficient.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

Idempotency-Keyheader

string

Request body (required)

Request body

application/json

StudioGenerateImageBody

Generate a static image (pose). Cost: 1 credit.

variant_idstring · uuid

Approved mascot variant for new content. Omit for Original when creating a new pose; when editing an explicit source asset, omission preserves its saved context. Animation loops preserve the generated source pose receipt; an explicit conflicting variant returns 409 unless that variant intentionally includes the source among its references. For transitions, the two poses determine their own before/after contexts. For uploaded references without receipts, a matching selected variant resolves the context; ambiguous shared uploads return 409 before charging. List variants with GET /v1/mascots/{id}/variants. Playback activation does not change generation selection.

namestring

Name for the new item. Required when creating a new item. Omit when passing item_id.

item_idstring · uuid

Existing item ID in this mascot. Pass this to add a new asset to an existing item, or to animate/edit its current image. For animations and edits, prefer item_id over source_image_asset_id so the API can resolve the source image from the item.

visual_referencesarray

One-time visual references for this generation only. Use for pose, expression, motion, props, style, or scene cues. These do not become mascot mascot references and do not update the mascot style card.

Items: 0 to 4

Nested fields

asset_idstring · uuid

Existing image asset ID to use as a one-time visual reference.

urlstring · uri

Public image URL to use as a one-time visual reference.

rolestring

What the model should borrow from this image.

Values: "pose", "expression", "motion", "prop", "style", "scene"

notestring

Optional instruction for this reference, e.g. "closed-mouth smile".

Length: 0 to 300 characters

typestring · required

Values: "image"

image_promptstring

What the character is doing in the image, e.g. "waving hello with a big smile".

StudioGenerateAnimationBody

variant_idstring · uuid

Approved mascot variant for new content. Omit for Original when creating a new pose; when editing an explicit source asset, omission preserves its saved context. Animation loops preserve the generated source pose receipt; an explicit conflicting variant returns 409 unless that variant intentionally includes the source among its references. For transitions, the two poses determine their own before/after contexts. For uploaded references without receipts, a matching selected variant resolves the context; ambiguous shared uploads return 409 before charging. List variants with GET /v1/mascots/{id}/variants. Playback activation does not change generation selection.

namestring

Name for the new item. Required when creating a new item. Omit when passing item_id.

item_idstring · uuid

animation_modelstring

Same choices as Studio: standard costs 2 credits/sec (2–15s); premium costs 6 credits/sec (4–30s). Both default to 5s. Omit to preserve legacy generation at 5 credits/sec (4–10s, default 4s).

Values: "standard", "premium"

durationinteger

Range: 2 to 30

typestring · required

Values: "animation"

animation_promptstring

image_promptstring

Used only when no source image exists. The character description that gets passed to image generation before animation starts.

source_image_asset_idstring · uuid

source_image_cropobject

Nested fields

xinteger · required

Range: 0 to unbounded

yinteger · required

Range: 0 to unbounded

widthinteger · required

Range: 0 to unbounded

heightinteger · required

Range: 0 to unbounded

end_image_cropobject

Optional square crop for end_image_asset_id, in pixels after EXIF orientation. Defaults to a centered square for non-square end frames. Requires end_image_asset_id.

Nested fields

xinteger · required

Range: 0 to unbounded

yinteger · required

Range: 0 to unbounded

widthinteger · required

Range: 0 to unbounded

heightinteger · required

Range: 0 to unbounded

end_image_asset_idstring · uuid

loopboolean

Whether the animation loops seamlessly. Defaults to true. Automatically set to false when end_image_asset_id is provided.

reverseboolean

Reverse an existing video. Used with reverse_of_video_asset_id. Costs 0 credits.

reverse_of_video_asset_idstring · uuid

Asset ID of the forward video to reverse. Required when reverse is true.

auto_reverseboolean

Transitions only: also generate the reverse transition (end to source) at 0 extra credits. Requires source_image_asset_id + end_image_asset_id. Response includes a reverse_job field.

reverse_namestring

Name for the auto-generated reverse item. Defaults to "<item name> (Reverse)".

sizesarray

Requested animation size variants in pixels, e.g. [480, 360]. Filtered against the mascot settings. No extra credit cost.

Nested fields

integer

speechobject

Nested fields

scriptstring

Length: 1 to 15000 characters

textstring

The words alone, instead of script. Masko writes the movements, following direction when given, and returns the script it used.

Length: 1 to 7500 characters

directionstring

With text: how the mascot should perform the line, e.g. "excited about what he does, points at the docs at the end".

Length: 0 to 500 characters

languagestring

ISO 639-1 code of the line. Omit it to detect the language from the words.

Pattern: ^[a-z]{2}$

dry_runboolean

With speech: return the estimate (and the script, when Masko writes the movements) without charging or generating.

StudioGenerateEditBody

Edit an existing image or video with natural-language instructions. Cost: 1 credit for images, 5 credits per second for videos, rounded up to a whole credit.

variant_idstring · uuid

Approved mascot variant for new content. Omit for Original when creating a new pose; when editing an explicit source asset, omission preserves its saved context. Animation loops preserve the generated source pose receipt; an explicit conflicting variant returns 409 unless that variant intentionally includes the source among its references. For transitions, the two poses determine their own before/after contexts. For uploaded references without receipts, a matching selected variant resolves the context; ambiguous shared uploads return 409 before charging. List variants with GET /v1/mascots/{id}/variants. Playback activation does not change generation selection.

namestring

Name for the new item. Required when creating a new item. Omit when passing item_id.

item_idstring · uuid

visual_referencesarray

Items: 0 to 4

Nested fields

asset_idstring · uuid

Existing image asset ID to use as a one-time visual reference.

urlstring · uri

Public image URL to use as a one-time visual reference.

rolestring

What the model should borrow from this image.

Values: "pose", "expression", "motion", "prop", "style", "scene"

notestring

Optional instruction for this reference, e.g. "closed-mouth smile".

Length: 0 to 300 characters

typestring · required

Values: "edit"

edit_instructionsstring · required

What to change on the source asset, e.g. "add a santa hat". Required.

source_image_asset_idstring · uuid

Asset ID of the image to edit. Use data.asset_ids.image from a previous /generate response. If you pass item_id, the source is resolved from the item automatically.

source_video_asset_idstring · uuid

Completed 2–15 second video in this mascot to edit (H3 Max, 768p before the 720p exports). Duration and aspect ratio are preserved. Uses the source clip and its source item. The edit opens and ends on the poses the clip was made between (a loop on its pose, a transition on its two poses), so it still joins the clips around it; a clip without a saved pose at one end is edited without that frame. For transition clips, edits preserve both saved endpoint identities and their order; variant_id does not restyle the whole clip. The edit prompt is recorded in generation_context.transition_edit.

StudioGenerateLogoBody

variant_idstring · uuid

Approved mascot variant for new content. Omit for Original when creating a new pose; when editing an explicit source asset, omission preserves its saved context. Animation loops preserve the generated source pose receipt; an explicit conflicting variant returns 409 unless that variant intentionally includes the source among its references. For transitions, the two poses determine their own before/after contexts. For uploaded references without receipts, a matching selected variant resolves the context; ambiguous shared uploads return 409 before charging. List variants with GET /v1/mascots/{id}/variants. Playback activation does not change generation selection.

namestring

Name for the new item. Required when creating a new item. Omit when passing item_id.

item_idstring · uuid

typestring · required

Values: "logo"

request_idstring · uuid

Stable retry key. Requires item_id; reuse unchanged after an uncertain response.

logo_style_idstring

Preset from GET /v1/logo-styles. Explicit style name/instruction override preset fields.

Values: "graphic-app-icon", "cut-paper", "soft-depth", "geometric", "abstract-symbol", "monoline-symbol", "negative-space", "retro-emblem", "hand-drawn"

logo_descriptionstring

What the logo should look like, e.g. "iconic face-only, circular badge". Defaults to "Iconic representation of the character".

logo_style_namestring

Short label for the logo style, e.g. "Flat", "Retro". Defaults to "Flat".

logo_style_instructionstring

Detailed style instructions, e.g. "Flat design with solid colors, no gradients".

StudioGenerateBackgroundBody

variant_idstring · uuid

Approved mascot variant for new content. Omit for Original when creating a new pose; when editing an explicit source asset, omission preserves its saved context. Animation loops preserve the generated source pose receipt; an explicit conflicting variant returns 409 unless that variant intentionally includes the source among its references. For transitions, the two poses determine their own before/after contexts. For uploaded references without receipts, a matching selected variant resolves the context; ambiguous shared uploads return 409 before charging. List variants with GET /v1/mascots/{id}/variants. Playback activation does not change generation selection.

namestring

Name for the new item. Required when creating a new item. Omit when passing item_id.

item_idstring · uuid

typestring · required

Values: "background"

purposestring

Length: 1 to 120 characters

placestring

Values: "phone_screen", "phone_header", "square", "web_hero", "banner"

descriptionstring

Optional words for the place, e.g. "a quiet meadow under a big sky". Without it the place fits the mascot's style and world.

Length: 0 to 500 characters

source_asset_idstring · uuid

For a new background: a completed picture of the mascot to use as the style sample. Defaults to its first reference. The mascot itself never appears in the background.

source_image_asset_idstring · uuid

To change a background: the background to start from. Pair it with place (another shape), edit_instructions (e.g. "the same place at night"), or both.

edit_instructionsstring

When changing a background: what to change, e.g. "the same place at night".

Length: 0 to 1000 characters

Responses

200 Talking estimate (speech with dry_run)

application/json

dataobject · required

Nested fields

dry_runboolean · required

Values: true

scriptstring · required

estimateobject · required

Talking animations only.

Nested fields

speech_secondsnumber · required

Estimated length of the spoken line.

durationinteger · required

Most likely video length in seconds.

max_durationinteger · required

The longest the video could need; the charge is based on it.

creditsinteger · required

Charged now: max_duration at 2 credits per second. Unused seconds are refunded once the voice is recorded.

too_longboolean · required

202 Generation job started

application/json

dataobject · required

Nested fields

job_idstring · uuid · required

statusstring · required

Values: "pending", "processing", "completed", "failed"

typestring · required

Values: "image", "animation", "edit", "logo", "reverse"

item_idstring · uuid · required

item_namestring · required

estimated_costnumber · required

asset_idsobject

urlsobject

estimateobject

Talking animations only.

Nested fields

speech_secondsnumber · required

Estimated length of the spoken line.

durationinteger · required

Most likely video length in seconds.

max_durationinteger · required

The longest the video could need; the charge is based on it.

creditsinteger · required

Charged now: max_duration at 2 credits per second. Unused seconds are refunded once the voice is recorded.

too_longboolean · required

scriptstring

Talking animations only: the line with its movements, as performed.

poll_urlstring · required

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

402 Insufficient credits

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Generate"
  ],
  "summary": "Generate image or animation",
  "description": "Starts an async generation job. Returns 202 with `data.job_id` - poll via GET `/v1/jobs/{id}` (or pass `?wait=true` for long-polling). Cost by type: image=1, animation=2/sec with animation_model=standard (2–15s) or 6/sec with animation_model=premium (4–30s), default 5s for either choice (+1 if no source image); omitting animation_model preserves legacy 5/sec, 4–10s, default 4s, logo=5, edit=1 for images, background=3, reverse=0. For `type: animation`, you can skip providing a source image: pass only `animation_prompt` (and optionally `image_prompt`) and the system generates a fresh source image first, then animates it. To animate an uploaded image directly, pass its POST /v1/upload asset_id as source_image_asset_id with type=animation. The upload is imported into the mascot without changing references; no image-generation credits are charged. Existing mascot assets preserve their saved context. Before video generation, non-square starting and ending images are center-cropped to square; square images are reused unchanged. Optional source_image_crop and end_image_crop specify integer x, y, width and height in pixels after image orientation. Cropped copies preserve the originals and incur no extra credits. Invalid crops return 400 before charging. If you have an existing item, pass `item_id` to animate/edit its current image. For image generation and image edits, pass optional `visual_references` for one-time pose, expression, motion, prop, style, or scene cues; these references do not become mascot mascot references. Backgrounds use this endpoint with `type: \"background\"`: an empty place in the mascot's own style, with no mascot in it and a spot where its animation plays on top. `place` sets the shape (phone_screen, phone_header, square, web_hero, banner) and `description` optionally describes the place; optional `source_asset_id` selects the mascot picture used as the style sample. To change a background, pass its `source_image_asset_id` with another `place`, `edit_instructions`, or both; the two source fields are mutually exclusive. `type: \"scene\"` was replaced by `type: \"background\"` and returns 400. Talking animations: pass `speech` with `type: animation` and the mascot says the line in its voice (see the Voice endpoints). The length follows the speech, 5 seconds to 5 minutes at 2 credits per second; the receipt charges the longest the line could need and unused seconds are refunded once the voice is recorded. Talking adds audio (MP3) and transcript (JSON) assets. With `dry_run: true` it returns 200 with the estimate instead. Returns 409 with details.reason voice_required when the mascot has no voice yet. Returns 402 if credits are insufficient.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.",
      "schema": {
        "type": "string",
        "maxLength": 255
      }
    }
  ],
  "requestBody": {
    "required": true,
    "description": "Request body",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/StudioGenerateBody"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Talking estimate (speech with dry_run)",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/TalkingDryRunResponse"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "202": {
      "description": "Generation job started",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/GenerateAsyncResponse"
          },
          "example": {
            "data": {
              "job_id": "b87c9579-7460-4bd0-aa54-77991615dfef",
              "status": "pending",
              "type": "image",
              "item_id": "e328c567-0965-42fc-90b5-7ff6faa61b25",
              "item_name": "wave",
              "estimated_cost": 1,
              "asset_ids": {
                "image": "a8b158bb-5698-431a-b0f1-98ee30228b11"
              },
              "urls": {
                "transparent_image": "https://assets.masko.ai/fda8417d/cat-api-test-1776591702/wave-91a9ac20.png",
                "image": "https://assets.masko.ai/fda8417d/cat-api-test-1776591702/wave-a8b158bb.png"
              },
              "poll_url": "/api/v1/jobs/b87c9579-7460-4bd0-aa54-77991615dfef?api_version=2026-09-26"
            }
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "402": {
      "description": "Insufficient credits",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    }
  },
  "operationId": "generateMascot",
  "x-masko-api-version": "2026-09-26"
}

POST/v1/mascots/{id}/animations/reference-videoAnimate a mascot from a reference video

From Video uses Premium to transfer reference motion to your mascot. Upload a video and its first frame through POST /v1/upload, then provide their asset IDs. Source assets must be completed, active, and accessible to the credential; mascot assets must belong to its workspace. Creates one animation item plus start and end pose items, with MP4, transparent WebM/HEVC, and pose images. Costs 6 credits per output second plus 1 image credit, so the default 5s costs 31 credits. Output duration is 4–30 whole seconds. Standard is not supported for this operation. Returns 202; poll the returned job until completed. Do not resubmit while the job is running.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

Idempotency-Keyheader

string

Request body (required)

Request body

application/json

video_asset_idstring · uuid · required

Owned, completed video asset containing the reference motion. Upload an MP4 or WebM with POST /v1/upload first.

first_frame_asset_idstring · uuid · required

Owned, completed image asset showing the first frame of the reference video. Upload it with POST /v1/upload.

namestring · required

Name for the animation. Start and end pose items are also created.

Length: 1 to 255 characters

promptstring

Optional instructions for the mascot pose and appearance.

Length: 0 to 10000 characters

durationinteger

Output duration in whole seconds, 4–30. Default 5. Premium costs 6 credits/sec plus 1 image credit.

Default: 5

Range: 4 to 30

animation_modelstring

From Video always uses Premium. Standard is available for image-to-video animation through /generate.

Values: "premium"

Default: "premium"

variant_idstring · uuid

Optional approved mascot variant to animate.

context_asset_idstring · uuid

Optional asset in this mascot whose saved mascot context is reused when variant_id is omitted.

Responses

202 Reference video job started

application/json

dataobject · required

Nested fields

job_idstring · uuid · required

item_idstring · uuid · required

start_item_idstring · uuid · required

end_item_idstring · uuid · required

asset_idstring · uuid · required

asset_idsobject · required

Nested fields

mascot_imagestring · uuid · required

videostring · uuid · required

webmstring · uuid · required

hevcstring · uuid · required

start_imagestring · uuid · required

start_transparentstring · uuid · required

end_imagestring · uuid · required

end_transparentstring · uuid · required

estimated_costinteger · required

poll_urlstring · required

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

402 Insufficient credits

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Generate"
  ],
  "summary": "Animate a mascot from a reference video",
  "description": "From Video uses Premium to transfer reference motion to your mascot. Upload a video and its first frame through POST /v1/upload, then provide their asset IDs. Source assets must be completed, active, and accessible to the credential; mascot assets must belong to its workspace. Creates one animation item plus start and end pose items, with MP4, transparent WebM/HEVC, and pose images. Costs 6 credits per output second plus 1 image credit, so the default 5s costs 31 credits. Output duration is 4–30 whole seconds. Standard is not supported for this operation. Returns 202; poll the returned job until completed. Do not resubmit while the job is running.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.",
      "schema": {
        "type": "string",
        "maxLength": 255
      }
    }
  ],
  "requestBody": {
    "required": true,
    "description": "Request body",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/StudioReferenceVideoBody"
        }
      }
    }
  },
  "responses": {
    "202": {
      "description": "Reference video job started",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ReferenceVideoAsyncResponse"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "402": {
      "description": "Insufficient credits",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    }
  },
  "operationId": "createMascotAnimationReferenceVideo",
  "x-masko-api-version": "2026-09-26"
}

POST/v1/mascots/{id}/generate-batchBatch-generate multiple items

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

Idempotency-Keyheader

string

Request body (required)

Request body

application/json

requestsarray · required

Items: 1 to 10

Nested fields

StudioGenerateImageBody

Generate a static image (pose). Cost: 1 credit.

variant_idstring · uuid

Approved mascot variant for new content. Omit for Original when creating a new pose; when editing an explicit source asset, omission preserves its saved context. Animation loops preserve the generated source pose receipt; an explicit conflicting variant returns 409 unless that variant intentionally includes the source among its references. For transitions, the two poses determine their own before/after contexts. For uploaded references without receipts, a matching selected variant resolves the context; ambiguous shared uploads return 409 before charging. List variants with GET /v1/mascots/{id}/variants. Playback activation does not change generation selection.

namestring

Name for the new item. Required when creating a new item. Omit when passing item_id.

item_idstring · uuid

visual_referencesarray

Items: 0 to 4

Nested fields

asset_idstring · uuid

Existing image asset ID to use as a one-time visual reference.

urlstring · uri

Public image URL to use as a one-time visual reference.

rolestring

What the model should borrow from this image.

Values: "pose", "expression", "motion", "prop", "style", "scene"

notestring

Optional instruction for this reference, e.g. "closed-mouth smile".

Length: 0 to 300 characters

typestring · required

Values: "image"

image_promptstring

What the character is doing in the image, e.g. "waving hello with a big smile".

StudioGenerateAnimationBody

variant_idstring · uuid

Approved mascot variant for new content. Omit for Original when creating a new pose; when editing an explicit source asset, omission preserves its saved context. Animation loops preserve the generated source pose receipt; an explicit conflicting variant returns 409 unless that variant intentionally includes the source among its references. For transitions, the two poses determine their own before/after contexts. For uploaded references without receipts, a matching selected variant resolves the context; ambiguous shared uploads return 409 before charging. List variants with GET /v1/mascots/{id}/variants. Playback activation does not change generation selection.

namestring

Name for the new item. Required when creating a new item. Omit when passing item_id.

item_idstring · uuid

animation_modelstring

Same choices as Studio: standard costs 2 credits/sec (2–15s); premium costs 6 credits/sec (4–30s). Both default to 5s. Omit to preserve legacy generation at 5 credits/sec (4–10s, default 4s).

Values: "standard", "premium"

durationinteger

Range: 2 to 30

typestring · required

Values: "animation"

animation_promptstring

image_promptstring

Used only when no source image exists. The character description that gets passed to image generation before animation starts.

source_image_asset_idstring · uuid

source_image_cropobject

Nested fields

xinteger · required

Range: 0 to unbounded

yinteger · required

Range: 0 to unbounded

widthinteger · required

Range: 0 to unbounded

heightinteger · required

Range: 0 to unbounded

end_image_cropobject

Optional square crop for end_image_asset_id, in pixels after EXIF orientation. Defaults to a centered square for non-square end frames. Requires end_image_asset_id.

Nested fields

xinteger · required

Range: 0 to unbounded

yinteger · required

Range: 0 to unbounded

widthinteger · required

Range: 0 to unbounded

heightinteger · required

Range: 0 to unbounded

end_image_asset_idstring · uuid

loopboolean

Whether the animation loops seamlessly. Defaults to true. Automatically set to false when end_image_asset_id is provided.

reverseboolean

Reverse an existing video. Used with reverse_of_video_asset_id. Costs 0 credits.

reverse_of_video_asset_idstring · uuid

Asset ID of the forward video to reverse. Required when reverse is true.

auto_reverseboolean

Transitions only: also generate the reverse transition (end to source) at 0 extra credits. Requires source_image_asset_id + end_image_asset_id. Response includes a reverse_job field.

reverse_namestring

Name for the auto-generated reverse item. Defaults to "<item name> (Reverse)".

sizesarray

Requested animation size variants in pixels, e.g. [480, 360]. Filtered against the mascot settings. No extra credit cost.

Nested fields

integer

speechobject

Nested fields

scriptstring

Length: 1 to 15000 characters

textstring

The words alone, instead of script. Masko writes the movements, following direction when given, and returns the script it used.

Length: 1 to 7500 characters

directionstring

With text: how the mascot should perform the line, e.g. "excited about what he does, points at the docs at the end".

Length: 0 to 500 characters

languagestring

ISO 639-1 code of the line. Omit it to detect the language from the words.

Pattern: ^[a-z]{2}$

dry_runboolean

With speech: return the estimate (and the script, when Masko writes the movements) without charging or generating.

StudioGenerateEditBody

Edit an existing image or video with natural-language instructions. Cost: 1 credit for images, 5 credits per second for videos, rounded up to a whole credit.

variant_idstring · uuid

Approved mascot variant for new content. Omit for Original when creating a new pose; when editing an explicit source asset, omission preserves its saved context. Animation loops preserve the generated source pose receipt; an explicit conflicting variant returns 409 unless that variant intentionally includes the source among its references. For transitions, the two poses determine their own before/after contexts. For uploaded references without receipts, a matching selected variant resolves the context; ambiguous shared uploads return 409 before charging. List variants with GET /v1/mascots/{id}/variants. Playback activation does not change generation selection.

namestring

Name for the new item. Required when creating a new item. Omit when passing item_id.

item_idstring · uuid

visual_referencesarray

Items: 0 to 4

Nested fields

asset_idstring · uuid

Existing image asset ID to use as a one-time visual reference.

urlstring · uri

Public image URL to use as a one-time visual reference.

rolestring

What the model should borrow from this image.

Values: "pose", "expression", "motion", "prop", "style", "scene"

notestring

Optional instruction for this reference, e.g. "closed-mouth smile".

Length: 0 to 300 characters

typestring · required

Values: "edit"

edit_instructionsstring · required

What to change on the source asset, e.g. "add a santa hat". Required.

source_image_asset_idstring · uuid

Asset ID of the image to edit. Use data.asset_ids.image from a previous /generate response. If you pass item_id, the source is resolved from the item automatically.

source_video_asset_idstring · uuid

StudioGenerateLogoBody

variant_idstring · uuid

Approved mascot variant for new content. Omit for Original when creating a new pose; when editing an explicit source asset, omission preserves its saved context. Animation loops preserve the generated source pose receipt; an explicit conflicting variant returns 409 unless that variant intentionally includes the source among its references. For transitions, the two poses determine their own before/after contexts. For uploaded references without receipts, a matching selected variant resolves the context; ambiguous shared uploads return 409 before charging. List variants with GET /v1/mascots/{id}/variants. Playback activation does not change generation selection.

namestring

Name for the new item. Required when creating a new item. Omit when passing item_id.

item_idstring · uuid

typestring · required

Values: "logo"

request_idstring · uuid

Stable retry key. Requires item_id; reuse unchanged after an uncertain response.

logo_style_idstring

Preset from GET /v1/logo-styles. Explicit style name/instruction override preset fields.

Values: "graphic-app-icon", "cut-paper", "soft-depth", "geometric", "abstract-symbol", "monoline-symbol", "negative-space", "retro-emblem", "hand-drawn"

logo_descriptionstring

What the logo should look like, e.g. "iconic face-only, circular badge". Defaults to "Iconic representation of the character".

logo_style_namestring

Short label for the logo style, e.g. "Flat", "Retro". Defaults to "Flat".

logo_style_instructionstring

Detailed style instructions, e.g. "Flat design with solid colors, no gradients".

StudioGenerateBackgroundBody

variant_idstring · uuid

Approved mascot variant for new content. Omit for Original when creating a new pose; when editing an explicit source asset, omission preserves its saved context. Animation loops preserve the generated source pose receipt; an explicit conflicting variant returns 409 unless that variant intentionally includes the source among its references. For transitions, the two poses determine their own before/after contexts. For uploaded references without receipts, a matching selected variant resolves the context; ambiguous shared uploads return 409 before charging. List variants with GET /v1/mascots/{id}/variants. Playback activation does not change generation selection.

namestring

Name for the new item. Required when creating a new item. Omit when passing item_id.

item_idstring · uuid

typestring · required

Values: "background"

purposestring

Length: 1 to 120 characters

placestring

Values: "phone_screen", "phone_header", "square", "web_hero", "banner"

descriptionstring

Optional words for the place, e.g. "a quiet meadow under a big sky". Without it the place fits the mascot's style and world.

Length: 0 to 500 characters

source_asset_idstring · uuid

For a new background: a completed picture of the mascot to use as the style sample. Defaults to its first reference. The mascot itself never appears in the background.

source_image_asset_idstring · uuid

To change a background: the background to start from. Pair it with place (another shape), edit_instructions (e.g. "the same place at night"), or both.

edit_instructionsstring

When changing a background: what to change, e.g. "the same place at night".

Length: 0 to 1000 characters

Responses

202 Batch generation jobs started

application/json

dataobject · required

Nested fields

jobsarray · required

Nested fields

job_idstring · uuid · required

statusstring · required

Values: "pending", "processing", "completed", "failed"

typestring · required

Values: "image", "animation", "edit", "logo", "reverse"

item_idstring · uuid · required

item_namestring · required

estimated_costnumber · required

asset_idsobject

urlsobject

estimateobject

Talking animations only.

Nested fields

speech_secondsnumber · required

Estimated length of the spoken line.

durationinteger · required

Most likely video length in seconds.

max_durationinteger · required

The longest the video could need; the charge is based on it.

creditsinteger · required

Charged now: max_duration at 2 credits per second. Unused seconds are refunded once the voice is recorded.

too_longboolean · required

scriptstring

Talking animations only: the line with its movements, as performed.

poll_urlstring · required

total_costnumber · required

poll_urlstring · required

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

402 Insufficient credits

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Generate"
  ],
  "summary": "Batch-generate multiple items",
  "description": "Starts multiple generation jobs in one call (up to the per-request cap). Returns 202 with an array of `data.jobs[]`, each with its own `job_id`. Cost is summed across all items. Returns 402 if credits are insufficient for the whole batch.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.",
      "schema": {
        "type": "string",
        "maxLength": 255
      }
    }
  ],
  "requestBody": {
    "required": true,
    "description": "Request body",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/StudioGenerateBatchBody"
        }
      }
    }
  },
  "responses": {
    "202": {
      "description": "Batch generation jobs started",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/BatchAsyncResponse"
          },
          "example": {
            "data": {
              "jobs": [
                {
                  "job_id": "fe21477f-7e46-448f-bfdb-96eac80205b8",
                  "item_id": "e8ca0d1b-b445-46f6-862f-26b26ac2c6ff",
                  "item_name": "sitting",
                  "status": "pending",
                  "estimated_cost": 1,
                  "asset_ids": {
                    "image": "25dc5edf-bf41-4a7f-ba23-b783ea2718d8"
                  },
                  "urls": {
                    "transparent_image": "https://assets.masko.ai/fda8417d/cat-api-test-1776591702/sitting-fb7bbd6f.png",
                    "image": "https://assets.masko.ai/fda8417d/cat-api-test-1776591702/sitting-25dc5edf.png"
                  }
                }
              ],
              "total_cost": 2,
              "poll_url": "/api/v1/jobs?api_version=2026-09-26"
            }
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "402": {
      "description": "Insufficient credits",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    }
  },
  "operationId": "generateBatchMascot",
  "x-masko-api-version": "2026-09-26"
}

GET/v1/mascots/{id}/suggestionsSuggest action poses

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

variant_idquery

Use this approved mascot variant for suggestions. Omit for Original.

string

Responses

200 Suggested actions

application/json

dataobject · required

Nested fields

suggestionsarray · required

Nested fields

string

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Generate"
  ],
  "summary": "Suggest action poses",
  "description": "Returns AI-generated action/pose suggestions (e.g. \"waving\", \"thinking\") tailored to the same resolved parent-plus-child mascot context used by generation. Use these as prompts for POST `/v1/mascots/{id}/generate`. No credit cost.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "schema": {
        "type": "string",
        "format": "uuid",
        "description": "Use this approved mascot variant for suggestions. Omit for Original."
      },
      "required": false,
      "description": "Use this approved mascot variant for suggestions. Omit for Original.",
      "name": "variant_id",
      "in": "query"
    }
  ],
  "responses": {
    "200": {
      "description": "Suggested actions",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SuggestionsResponse"
          },
          "example": {
            "data": {
              "suggestions": [
                "Curious Head Tilt",
                "Wide Eyed Stare",
                "Slow Clay Blink",
                "Gentle Tail Wag",
                "Heavy Paw Waddle",
                "Playful Pounce",
                "Happy Ear Twitch"
              ]
            }
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    }
  },
  "operationId": "listMascotSuggestions",
  "x-masko-api-version": "2026-09-26"
}

GET/v1/mascots/{id}/backgrounds/suggestionsSuggest backgrounds for a purpose

Returns five places for what a background is for, from the mascot's world: a preset purpose (splash, onboarding, signup, home, paywall, reward, empty, loading, landing, banner) or your own words. For your own words it also picks the place that fits. Ideas for a preset are saved and returned again until refresh=true. Send one as description, with the same purpose, to POST /v1/mascots/{id}/generate with type: "background". No credit cost.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

purposequery

What the background is for: splash, onboarding, signup, home, paywall, reward, empty, loading, landing or banner, or your own words, e.g. "a quiz result page".

string

refreshquery

true writes new ideas for a preset purpose instead of returning the saved ones.

string · true, false

variant_idquery

Approved mascot variant whose world the ideas come from.

string

Responses

200 Five places for the purpose

application/json

dataobject · required

Nested fields

purposestring · required

placestring · required

Values: "phone_screen", "phone_header", "square", "web_hero", "banner"

suggestionsarray · required

Nested fields

titlestring · required

descriptionstring · required

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Generate"
  ],
  "summary": "Suggest backgrounds for a purpose",
  "description": "Returns five places for what a background is for, from the mascot's world: a preset purpose (splash, onboarding, signup, home, paywall, reward, empty, loading, landing, banner) or your own words. For your own words it also picks the place that fits. Ideas for a preset are saved and returned again until refresh=true. Send one as `description`, with the same `purpose`, to POST `/v1/mascots/{id}/generate` with `type: \"background\"`. No credit cost.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "schema": {
        "type": "string",
        "minLength": 1,
        "maxLength": 120,
        "default": "splash",
        "description": "What the background is for: splash, onboarding, signup, home, paywall, reward, empty, loading, landing or banner, or your own words, e.g. \"a quiz result page\"."
      },
      "required": false,
      "description": "What the background is for: splash, onboarding, signup, home, paywall, reward, empty, loading, landing or banner, or your own words, e.g. \"a quiz result page\".",
      "name": "purpose",
      "in": "query"
    },
    {
      "schema": {
        "type": "string",
        "enum": [
          "true",
          "false"
        ],
        "description": "true writes new ideas for a preset purpose instead of returning the saved ones."
      },
      "required": false,
      "description": "true writes new ideas for a preset purpose instead of returning the saved ones.",
      "name": "refresh",
      "in": "query"
    },
    {
      "schema": {
        "type": "string",
        "format": "uuid",
        "description": "Approved mascot variant whose world the ideas come from."
      },
      "required": false,
      "description": "Approved mascot variant whose world the ideas come from.",
      "name": "variant_id",
      "in": "query"
    }
  ],
  "responses": {
    "200": {
      "description": "Five places for the purpose",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/BackgroundSuggestionsResponse"
          },
          "example": {
            "data": {
              "purpose": "a quiz result page",
              "place": "phone_screen",
              "suggestions": [
                {
                  "title": "Sunny meadow stage",
                  "description": "A wide meadow under a pale sky, the grass flattening into a clear patch in the middle."
                }
              ]
            }
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    }
  },
  "operationId": "listMascotBackgroundSuggestions",
  "x-masko-api-version": "2026-09-26"
}

PATCH/v1/mascots/{id}/settingsUpdate mascot settings

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

Request body (required)

Request body

application/json

publish_paramsobject

Nested fields

image_exportsobject

Nested fields

enabledboolean · required

sourcesarray · required

Items: 1 to 3

Nested fields

string · original, transparent, sticker

formatsarray · required

Items: 1 to 2

Nested fields

string · png, webp

sizesarray · required

Items: 1 to 5

Nested fields

integer

prores_exportsobject

Automatically create original-delivery-size ProRes 4444 MOV files with alpha after transparent animations finish. Disabled by default.

Nested fields

enabledboolean · required

mkpk_exportsobject

Automatically create one .mkpk pack (ESP32 Masko SDK) per forward animation once its transparent video exists, all with the same width and settings. Disabled by default.

Nested fields

screen_widthinteger

Screen the pack is made for; the frames are centred on it. Set with screen_height. Defaults to the frame size.

Range: 16 to 1024

screen_heightinteger

Range: 16 to 1024

fpsinteger

Frames per second. Defaults to 24.

Range: 1 to 60

qualityinteger

JPEG quality from 1 to 100. Defaults to 75.

Range: 1 to 100

background_colorstring

Colour behind the mascot, as #RRGGBB. Defaults to black.

Pattern: ^#[0-9a-fA-F]{6}$

enabledboolean · required

sizeinteger

Frame width in pixels, a multiple of 16. Required when enabled.

Range: 32 to 1024

animation_sizesobject

Nested fields

enabledboolean · required

Whether animation size variants are generated.

sizesarray · required

Up to 2 smaller pixel widths to generate, from 32 to 719. Every animation already gets its 720 px files, so 720 and larger values are ignored. Common values: 480, 360, 240, 128.

Nested fields

number

force_refreshboolean

Responses

200 Settings updated

application/json

dataobject · required

Nested fields

updatedboolean · required

slugstring

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Settings"
  ],
  "summary": "Update mascot settings",
  "description": "Updates mascot export settings. image_exports configures future PNG/WebP derivatives of original, transparent and sticker images; it does not backfill existing images. animation_sizes takes up to 2 smaller widths below 720 px (every animation already gets its 720 px files, so 720 and larger values are ignored) and preserves existing behavior: changed settings may queue exports for existing animations as well as future outputs. Use POST /v1/mascots/{id}/exports for explicit image/video backfill, or the legacy size-variants endpoint for video-only repair. Returns settings_applied, size_variant_jobs and sizes_enabled. No credit cost.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    }
  ],
  "requestBody": {
    "required": true,
    "description": "Request body",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/UpdateSettingsBody"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Settings updated",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/UpdatedFlagResponse"
          },
          "example": {
            "data": {
              "updated": true
            }
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    }
  },
  "operationId": "updateMascotSettings",
  "x-masko-api-version": "2026-09-26"
}

POST/v1/mascots/{id}/size-variantsBackfill animation size variants

Starts idempotent jobs that make the files each completed animation in this mascot lacks: WebM, HEVC, stacked MP4 and stacked AV1, at the animation width and at each of up to 2 smaller sizes, made from its existing background removal. Normal pipeline usage sends {}: it uses the mascot configured animation_sizes, or [360] when no sizes are configured, and only makes missing files, so files that exist keep their URLs and animations made before AV1 get their AV1 files. force=true is an explicit admin recovery option that remakes every sized file too; do not use it for normal marketplace/canvas backfills or while relevant jobs are in flight. This endpoint does not regenerate source animations and does not toggle mascot settings.

Bearer authentication. Access depends on credential scope and workspace membership.

Parameters

idpath · required

string

Idempotency-Keyheader

string

Request body (required)

Request body

application/json

sizesarray

Up to 2 smaller pixel widths to generate. Defaults to the mascot's configured animation_sizes, or [360]. Every animation already gets its 720 px files, so 720 and larger values are ignored.

Nested fields

integer

forceboolean

Regenerate even sizes that already exist. Default false (idempotent: only missing sizes, never supersedes in-flight jobs).

Responses

200 Size variant jobs started

application/json

dataobject · required

Nested fields

size_variant_jobsinteger · required

Range: 0 to unbounded

sizesarray · required

Nested fields

integer

forceboolean · required

400 Validation error

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

401 Unauthorized

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

403 Forbidden

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

404 Not found

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

409 Conflict

application/json

errorobject · required

Nested fields

codestring · required

Stable machine-readable code. Switch on this.

messagestring · required

Human-readable explanation.

paramstring

The request field that caused the error, when there is one.

detailsobject

Extra context, for example issues for validation errors or required and balance for credits.

doc_urlstring · uri · required

Documentation for this error code.

request_idstring · required

Same value as the Request-Id header. Include it when contacting support.

OpenAPI operation

{
  "tags": [
    "Settings"
  ],
  "summary": "Backfill animation size variants",
  "description": "Starts idempotent jobs that make the files each completed animation in this mascot lacks: WebM, HEVC, stacked MP4 and stacked AV1, at the animation width and at each of up to 2 smaller sizes, made from its existing background removal. Normal pipeline usage sends `{}`: it uses the mascot configured `animation_sizes`, or `[360]` when no sizes are configured, and only makes missing files, so files that exist keep their URLs and animations made before AV1 get their AV1 files. `force=true` is an explicit admin recovery option that remakes every sized file too; do not use it for normal marketplace/canvas backfills or while relevant jobs are in flight. This endpoint does not regenerate source animations and does not toggle mascot settings.",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "required": true,
      "name": "id",
      "in": "path"
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.",
      "schema": {
        "type": "string",
        "maxLength": 255
      }
    }
  ],
  "requestBody": {
    "required": true,
    "description": "Request body",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/StudioGenerateSizeVariantsBody"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Size variant jobs started",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SizeVariantsResponse"
          },
          "example": {
            "data": {
              "size_variant_jobs": 3,
              "sizes": [
                360
              ],
              "force": false
            }
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "headers": {
        "Request-Id": {
          "description": "Unique ID of this request. Include it when contacting support.",
          "schema": {
            "type": "string",
            "example": "req_3f9c2a71d0b84e6a9c1f5e22"
          }
        },
        "Masko-API-Version": {
          "description": "Effective resource naming contract.",
          "schema": {
            "type": "string",
            "enum": [
              "2026-09-26"
            ]
          }
        }
      }
    }
  },
  "operationId": "createMascotSizeVariant",
  "x-masko-api-version": "2026-09-26"
}