Canvases

6 actions. Each is callable by the agent as a tool, over HTTP via /api/invoke, and (usually) from a UI page.

`canvases.list`

GET

List design canvases (tldraw docs), optionally scoped to a project/mission/subject.

AI tool: canvases_list
API: GET /api/invoke/canvases.list

Input

Field	Type	Required
`projectId`	string	—
`missionId`	string	—
`subjectId`	string	—
`limit`	integer	—
`offset`	integer	—
`orderBy`	string	—
`orderDir`	"asc" \| "desc"	—
`q`	string	—

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "projectId": {
      "type": "string",
      "minLength": 1
    },
    "missionId": {
      "type": "string",
      "minLength": 1
    },
    "subjectId": {
      "type": "string",
      "minLength": 1
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 500
    },
    "offset": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "orderBy": {
      "type": "string"
    },
    "orderDir": {
      "type": "string",
      "enum": [
        "asc",
        "desc"
      ]
    },
    "q": {
      "type": "string"
    }
  }
}

`canvases.get`

GET

Get a design canvas with its full tldraw document.

AI tool: canvases_get
API: GET /api/invoke/canvases.get

Input

Field	Type	Required	Description
`id`	string	yes

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1
    }
  },
  "required": [
    "id"
  ]
}

`canvases.create`

POST · mutating

Create a new design canvas.

AI tool: canvases_create
API: POST /api/invoke/canvases.create

Input

Field	Type	Required
`name`	string	yes
`description`	string	—
`document`	object	—
`projectId`	union	—
`missionId`	union	—
`subjectId`	union	—
`thumbnailUrl`	union	—
`createdBy`	union	—
`lastEditedBy`	union	—

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "description": {
      "default": "",
      "type": "string"
    },
    "document": {
      "default": {},
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "projectId": {
      "anyOf": [
        {
          "type": "string",
          "minLength": 1
        },
        {
          "type": "null"
        }
      ]
    },
    "missionId": {
      "anyOf": [
        {
          "type": "string",
          "minLength": 1
        },
        {
          "type": "null"
        }
      ]
    },
    "subjectId": {
      "anyOf": [
        {
          "type": "string",
          "minLength": 1
        },
        {
          "type": "null"
        }
      ]
    },
    "thumbnailUrl": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "createdBy": {
      "anyOf": [
        {
          "type": "string",
          "minLength": 1
        },
        {
          "type": "null"
        }
      ]
    },
    "lastEditedBy": {
      "anyOf": [
        {
          "type": "string",
          "minLength": 1
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "name"
  ]
}

`canvases.save`

PATCH · mutating

Save the full scene document state for a canvas (validated permissively).

AI tool: canvases_save
API: PATCH /api/invoke/canvases.save

Input

Field	Type	Required
`id`	string	yes
`document`	object	yes
`lastEditedBy`	string	—
`thumbnailUrl`	string	—

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1
    },
    "document": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "lastEditedBy": {
      "type": "string",
      "minLength": 1
    },
    "thumbnailUrl": {
      "type": "string"
    }
  },
  "required": [
    "id",
    "document"
  ]
}

`canvases.apply_ops`

POST · mutating

Apply granular scene ops (add/update/delete/move/reorder node, set background) to a canvas document and persist. Returns the updated canvas.

AI tool: canvases_apply_ops
API: POST /api/invoke/canvases.apply_ops

Input

Field	Type	Required
`id`	string	yes
`ops`	object[]	yes
`lastEditedBy`	string	—
`thumbnailUrl`	string	—

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1
    },
    "ops": {
      "type": "array",
      "items": {
        "type": "object",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {}
      }
    },
    "lastEditedBy": {
      "type": "string",
      "minLength": 1
    },
    "thumbnailUrl": {
      "type": "string"
    }
  },
  "required": [
    "id",
    "ops"
  ]
}

`canvases.presence`

POST · mutating

Broadcast or read ephemeral collaborator presence for a canvas (cursors, selection). Stored in document meta.presence.

AI tool: canvases_presence
API: POST /api/invoke/canvases.presence

Input

Field	Type	Required
`id`	string	yes
`cursor`	object	—
`selectedIds`	string[]	—
`userName`	string	—

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1
    },
    "cursor": {
      "type": "object",
      "properties": {
        "x": {
          "type": "number"
        },
        "y": {
          "type": "number"
        }
      },
      "required": [
        "x",
        "y"
      ]
    },
    "selectedIds": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "userName": {
      "type": "string"
    }
  },
  "required": [
    "id"
  ]
}