> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runchat.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Canvas

> Read and modify a Runchat canvas programmatically. Discover nodes, create or connect them, organize layout, and execute runs.



## OpenAPI

````yaml POST /{runchat_id}/canvas
openapi: 3.1.0
info:
  title: Runchat API
  description: API for executing Runchat flows and retrieving schema information.
  version: 1.0.0
servers:
  - url: https://runchat.com/api/v1
    description: Relative path for the API endpoints
security:
  - bearerAuth: []
tags:
  - name: Execution
    description: Endpoints related to running Runchat flows.
  - name: Schema
    description: Endpoints for retrieving Runchat flow structure and definitions.
  - name: Canvas
    description: >-
      Endpoints for programmatic canvas manipulation — reading, creating,
      connecting, and running nodes.
  - name: Jobs
    description: >-
      Endpoints for triggering saved Runchat jobs — scheduled flow runs and
      agent tasks.
paths:
  /{runchat_id}/canvas:
    parameters:
      - name: runchat_id
        in: path
        required: true
        description: The unique identifier for the Runchat flow.
        schema:
          type: string
    post:
      tags:
        - Canvas
      summary: Canvas Tool
      description: >-
        Execute a canvas tool to read, create, connect, update, or run nodes on
        a Runchat workflow. All canvas operations are dispatched through this
        single endpoint by specifying a `tool` name and its `args`.


        See the [Canvas Tools Reference](/api-reference/canvas-tools) for
        detailed parameter documentation for each tool.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CanvasRequest'
            examples:
              getCanvas:
                summary: Get canvas overview
                value:
                  tool: get_canvas
                  args: {}
              readNodes:
                summary: Read node details
                value:
                  tool: read_nodes
                  args:
                    node_ids:
                      - node_abc123
              createNode:
                summary: Create a prompt node
                value:
                  tool: create_prompt_node
                  args:
                    label: Summarizer
                    prompt: Summarize the input text
              createNodes:
                summary: Create multiple nodes at once (legacy create_node)
                value:
                  tool: create_node
                  args:
                    nodes:
                      - type: inputNode
                        label: Topic
                        initial_data:
                          input:
                            - robots
                        position:
                          x: 0
                          'y': 0
                      - type: promptNode
                        label: Write
                        initial_data:
                          prompt:
                            - Write a haiku about {{topic}}
                        position:
                          x: 420
                          'y': 0
              connectNodes:
                summary: Connect two nodes
                value:
                  tool: connect_nodes
                  args:
                    source_node_id: node_abc
                    target_node_id: node_xyz
                    source_handle: content
                    target_handle: prompt
              connectEdges:
                summary: Connect multiple edges at once
                value:
                  tool: connect_nodes
                  args:
                    edges:
                      - source_node_id: node_abc
                        target_node_id: node_def
                        target_handle: prompt
                      - source_node_id: node_def
                        target_node_id: node_ghi
                        target_handle: messages
      responses:
        '200':
          description: Successful tool execution.
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: object
                    description: Tool-specific result payload. Structure varies by tool.
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          description: Access denied — user does not have permission to this Runchat.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Runchat not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    CanvasRequest:
      type: object
      description: Request body for the canvas tool endpoint.
      properties:
        tool:
          type: string
          enum:
            - get_canvas
            - read_nodes
            - create_prompt_node
            - create_input_node
            - create_image_node
            - create_code_node
            - create_note
            - place_tool
            - create_artifact_node
            - create_node
            - update_node
            - connect_nodes
            - organize_nodes
            - delete_nodes
            - delete_edges
            - run_nodes
            - read_files
            - read_status
            - edit_file
            - create_files
            - delete_files
            - get_model_params
            - list_models
            - view_image
            - search_tools
            - inspect_tool
            - execute_tool
            - use_skill
            - publish_runchat
            - update_runchat
            - grasshopper_api
            - run_rhino_command
            - take_screenshot
          description: >-
            The canvas tool to execute. Each node type has its own creation tool
            (create_prompt_node, create_code_node, …); create_node remains as a
            legacy alias that also supports batch creation via a `nodes` array.
            See the Canvas Tools Reference for detailed parameter documentation
            for each tool.
        args:
          type: object
          additionalProperties: true
          description: >-
            Tool-specific arguments. The shape depends on which tool is being
            called.
      required:
        - tool
    Error:
      type: object
      properties:
        error:
          type: string
          description: A message describing the error.
      required:
        - error
  responses:
    BadRequest:
      description: >-
        Bad Request - The request could not be understood or was missing
        required parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalServerError:
      description: Internal Server Error - An unexpected error occurred on the server.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Bearer token authentication using Runchat API key. API keys can be
        created from the account menu

````