Skip to main content
The Canvas API uses a single endpoint to dispatch operations via the tool field. This page documents each tool and its parameters.
Using an MCP client like Claude, ChatGPT, or Cursor? The easiest way to give an agent these tools is the Runchat MCP server — it exposes every tool below (plus model discovery and skills) and handles auth for you. The REST endpoint documented here is for plain HTTP / scripted access.
All responses follow the shape { "result": { ... } }.
A machine-readable skill specification for this API is available at GET https://runchat.com/api/skills/canvas. AI agents can fetch this endpoint to learn the full tool schema automatically. We also include links to this in the ai-instructions metatag for any link to a workflow so you can simply share a link to a workflow and ask it to follow any instructions.

Typical workflow

  1. get_canvas — discover what’s on the canvas
  2. read_nodes — inspect specific nodes and their handles
  3. create_prompt_node / create_code_node / … / update_node / connect_nodes — build or modify the workflow
  4. organize_nodes — auto-layout the result
  5. run_nodes — execute the workflow

Canvas Tools

get_canvas

Get a high-level overview of all nodes and edges on the canvas. Returns node IDs, types, labels, positions, and edge connections. Paginated at 50 nodes per page.

read_nodes

Read the full state of one or more nodes by ID. Returns each parameter’s name, type, label, status, and current data values. Use this to find handle names for connect_nodes.

Creating nodes

Each node type has its own creation tool with a flat, type-specific schema — easier to call correctly than one polymorphic tool. Every creation tool shares these optional fields:
create_node (a single polymorphic call taking a type field) remains available as a legacy alias and is the only way to create several nodes in one call — see Creating multiple nodes.

create_prompt_node

Create an LLM node (promptNode) for reasoning, writing, analysis, or agent tasks. Output is on the messages handle; structured output (output_format) is on artifacts.

create_input_node

Create a user-input widget (inputNode). Its value is exposed on the content handle. One input node holds a whole list — set a list with values, not one node per item.

create_image_node

Create a media generation node (imageNode) — images, video, 3D, or audio. Generated media is on the image handle, and run_nodes returns its URL. For plain text-to-image, use the default model runware:400@2 with { "prompt": "..." }. For anything else, get the model’s parameter names from get_model_params. Params the model doesn’t define are reported back in a warning, and an unknown model_id is an error.

create_code_node

Create a code node (codeNode). Code executes on the server only when the node is run. Output is on the result handle by default. JavaScript nodes support multiple files: add a package.json and helper modules with create_files after creation (this upgrades the node to the bundler sandbox automatically). Other languages have a single entry file.

create_note

Create a markdown note (noteNode) for documentation, summaries, or links.

place_tool

Place a published tool (found with search_tools) onto the canvas as a runChatNode.

create_artifact_node

Create an artifact node (artifactNode) that saves or fetches an artifact (blog post, website, or app).

Creating multiple nodes

The legacy create_node tool takes a nodes array to create a whole pipeline in one call. Each item is a full node spec (type required), and an optional position lays it out. The response is { "count": N, "nodes": [ ... ] }.
Omit position on any node to let it auto-place — batched nodes chain left-to-right in creation order off the existing workflow. Relative positions (right_of etc.) can reference any node that already exists, including ones created by an earlier call; they cannot reference siblings in the same batch (their IDs are generated server-side). If you set positions yourself you don’t need to call organize_nodes.

update_node

Update an existing node’s label, model, or input values.

connect_nodes

Connect an output of one node to an input of another — one edge, or many at once via edges. Common handles: When you pass edges, the response is { "count": N, "edges": [ ... ] } with one result per edge — an edge that fails (e.g. an unknown handle) is reported individually without aborting the others.

organize_nodes

Auto-layout nodes on the canvas based on their connections. Call this after completing all node-creation and connect_nodes operations. The set expands automatically to every node connected to the ones you pass, and nodes the user has positioned manually are never moved — they act as fixed anchors the layout arranges itself around.

delete_nodes

Delete one or more nodes from the canvas. Also removes any connected edges.

delete_edges

Delete one or more edges (connections) from the canvas without deleting the nodes.

run_nodes

Execute one or more nodes on the canvas. Nodes run in dependency order — upstream nodes execute first. Returns each node’s status and, per output, the item count, type and — for hosted media and files — the URLs (up to 10), e.g. { "image": { "items": 1, "type": "image", "urls": ["https://…"] } }.
Running nodes may consume credits. Confirm with the user before calling this tool.

Tool Discovery

Find published tools (and the user’s own runchats) and run them directly, without first placing them on a canvas.
These tools operate on the published-tool library, not the current canvas. For inspect_tool and execute_tool the runchat_id in args names the tool to act on — the {runchat_id} in the endpoint URL is only the canvas/auth scope and is ignored by these tools.

search_tools

Search published tools and the user’s own runchats by keyword. Returns each tool’s runchat_id, name, description, and its input/output parameter names — enough to run it with execute_tool.

inspect_tool

Inspect a published tool to see its inputs/outputs and a digest of its internal nodes (models, prompts, code) and connections. Optional — use it to learn how a tool is built or before placing it on a canvas; not required to run a tool.

execute_tool

Run a published tool and return its outputs, without adding it to a canvas. Provide inputs keyed by the tool’s input parameter names (from search_tools); the result reports any inputs that didn’t match.
Running a tool spends the authenticated user’s credits. Confirm before running anything costly.

Media Tools

get_model_params

Get full parameter details for one or more models. Returns parameter names, types, and defaults — use these as params keys when creating an imageNode. runchat_id is optional for this tool.

view_image

Fetch an image from a URL for analysis. If the URL is a webpage rather than an image, a headless browser captures a viewport screenshot of it instead (spends credits). Over MCP, runchat_id is optional when passing url; it’s only needed with node_id.

Web Tools

First-party web search and page reading. Both spend the authenticated user’s credits. Search the web and get title/url/snippet results (Brave licensed index). Follow up with fetch_page on a result URL for full content.

fetch_page

Fetch a webpage in a headless browser (JavaScript executed) and return its content. Long pages are windowed: a truncated response includes next_offset — pass it back as offset to page through the rest (each page is a fresh render and billed call).

Code File Tools

Every codeNode exposes a uniform file model. JavaScript nodes have an entry file (index.ts, plain JS or TypeScript) plus optional additional files (package.json for npm deps, helper modules, static .html assets) — adding files upgrades the node to the bundler sandbox automatically. Other languages (html, rhino-python, rhino-csharp, blender-python, revit-csharp, archicad-python) have a single entry file. Entry filenames by language: Always call read_files (or read_nodes) first to discover the entry path — never guess based on language.

read_files

Read content from a code node. Returns each file’s path, line-numbered content, length, and whether it’s the entry file. Response includes code_mode, entry_file, and a files array of { path, entry, length, content } plus not_found if any requested paths are missing.

edit_file

Edit one file in a code node. Two modes:
  • Targeted edit — pass old_text + new_text. old_text must match exactly (whitespace + indentation) and be unique in the file. Empty new_text deletes the matched span.
  • Full overwrite — pass only new_text (omit old_text). Replaces the entire file.
Always call read_files first to see current content.

create_files

Create one or more new files in a JavaScript code node (e.g. package.json, lib/utils.ts, a static index.html asset). JavaScript nodes only — other languages have a single fixed entry file. Adding files upgrades the node to the bundler sandbox automatically. Errors if any path collides with the entry file or an existing file.

delete_files

Delete one or more non-entry files from a JavaScript code node. Cannot delete the entry file.

read_status

Read current error messages, status messages, preview errors, and console output for a code node. Use when debugging a failing run.

Search and Reference Tools

search_reference_images

Find real reference photographs and return them as direct image URLs you can use as image inputs, with title, source, page URL and photographer. Costs 1 credit per call, or 10 when brave is one of the sources.

search_docs

Search the Runchat documentation and return matching sections with their URLs. Free.

use_skill

Load a built-in guide that agents use when writing Runchat workflows, code and scripts. Returns the guide as text.

list_models

List the models available to the authenticated user, with model_id, name, modality, tags and cost. Use it to find valid model_ids for get_model_params, create_image_node and create_prompt_node.

Scene Tools

Read and edit the workflow’s shared 3D Scene. Units are metres, with Z up, X east and Y north.

read_scene

List every object in the scene with its id, kind, the values it was made from, who last changed it, and the box it occupies (world_min, world_max).

edit_scene

Add, change or remove objects. Operations apply in order; a failed operation is reported and the rest still apply. Each operation has an op of add, set (change only the fields passed) or remove (delete the object and everything inside it), plus: A mesh result includes the box it now fills, so you can check whether a model centred on its own origin needs lifting onto the ground.

view_scene

Render the scene and return the image, with objects labelled by name and id on a metric grid.

App Tools

Drive an app on the canvas: an HTML Code node with shared state and commands.

read_app

Return an app’s commands with their inputs, its state with who last wrote each key, and its revision (rev). With neither node_id nor artifact_id, list the apps on the canvas. All three app tools address an app the same way: node_id for an app on this canvas, or artifact_id for a published app or Rhino tool. With artifact_id, scope picks "user" (your own state in that app, the default) or "shared" (the state every viewer sees, which only the app’s owner can change).

app_command

Run one of the app’s commands, exactly as its interface would. Changes are written in one step and show up live for everyone with the app open. If someone else changed the app while the command ran, it is run again on the new state. Returns the command’s result and the new rev. Costs 1 credit.

edit_app_state

Write an app’s state directly, for when no command fits. Prefer app_command where one exists, since commands keep the state valid. Returns the new rev.

Publishing Tools

publish_runchat

Publish the runchat as a reusable tool. Each call releases a new version. Returns the version number and public slug.

update_runchat

Rename the runchat, set its tags or move it to a folder. Only the fields you pass change.

Artifact Tools

Create and update artifacts: hosted pages at runchat.com/artifacts/<handle>/<slug>. These tools don’t use the runchat_id in the URL.

create_artifact

Create and publish an artifact. The type follows from the content: Markdown becomes a blog post, an HTML document a website, HTML that uses window.runchat an app, and a tool.json manifest a Rhino CAD tool. Returns artifact_id and the URL.

get_artifact

Fetch an artifact’s name, entry file, URL, visibility and publish state.

update_artifact

Update an artifact you own and re-publish it. Only the fields you pass change.

Training Tools

Train LoRAs on your own images. See Training LoRAs. These tools don’t use the runchat_id in the URL.

list_training_runs

List your training runs, newest first, with status, base model, trigger word and, once complete, the model_url to pass to a LoRA-capable model’s loras parameter. Also returns the available trainers with their cost, base model and expected duration.

start_training

Start a training run. Spends the trainer’s listed cost in credits. Returns a request_id to follow with list_training_runs. Style trainers take a flat folder of images with optional captions. Edit trainers learn a change from before and after pairs: for each pair the zip holds NAME_start.EXT, NAME_end.EXT and NAME.txt with the edit instruction. Run use_skill with edit-lora-training for the full recipe.

CAD and ClipChat Tools

The endpoint also drives connected desktop apps. See CAD bridges for Rhino, Grasshopper, Blender, Revit, ArchiCAD and SketchUp. ClipChat’s editing tools are covered in the ClipChat guides.

Skill Endpoint

The Canvas API skill specification is available as a machine-readable document that AI agents can fetch to learn the full tool schema automatically.
Returns a Markdown document with YAML frontmatter containing the complete tool reference. The response includes:
  • API description and base URL
  • All tool schemas with parameter types and descriptions
  • Common handle names and workflow guidance
This is useful for integrating external AI agents (e.g. Claude, GPT) that need to discover and use the Canvas API programmatically.