Connectors API

Connectors are visual lines drawn between two widgets on a canvas. They represent relationships -- use them to link notes in a mind map, show data flow between components in an architecture diagram, or draw attention to connections between any two pieces of content.

Unlike most canvas widgets, connectors do not have location, depth, size, scale, or pinned properties. Their position is fully determined by their src and dst endpoint objects. Each endpoint attaches to a specific widget and can be positioned at a relative location along that widget's edge.

Connector Properties

id (string, uuid) -- Unique identifier assigned by the server. Read-only.
widget_type (string) -- Always "Connector". Read-only.
state (string) -- Widget state. Typically "normal".
type (string) -- The connector's line shape. Known values: "curve", "straight", "right-angle".
line_color (string) -- Line color as an RGBA hex string, e.g. "#e7e7f2ff". Patchable.
line_width (number) -- Line thickness in pixels. Patchable.

Source and Destination Endpoints

Each connector has a src (source) and dst (destination) object with identical structure:

id (string, uuid) -- The ID of the widget this endpoint connects to. Required on creation.
rel_location (object) -- Relative position on the target widget's bounding box as {"x": float, "y": float}. Values range from 0.0 (left/top edge) to 1.0 (right/bottom edge). For example, {"x": 0.5, "y": 0} places the endpoint at the top-center of the widget.
auto_location (boolean) -- When true, the server automatically determines the best attachment point. When false, the connector uses the rel_location value.
tip (string) -- Arrowhead style at this endpoint. Known values: "none", "solid-equilateral-triangle".

List Connectors

Returns all connectors on the specified canvas.

GET /api/v1/canvases/:canvas_id/connectors

Path parameters:

canvas_id (uuid, required) -- ID of the canvas

Query parameters:

subscribe (boolean, optional) -- Enable streaming updates. See Streaming.

Example request:

curl -H "Private-Token: YOUR_TOKEN" \
  https://canvus.example.com/api/v1/canvases/09348962-32aa-480d-b3d6-cacef4030ac2/connectors

Example response:

[
  {
    "dst": {
      "auto_location": false,
      "id": "9d928b20-2886-4c23-b86f-07d5a444ba72",
      "rel_location": {
        "x": 0,
        "y": 0.5
      },
      "tip": "solid-equilateral-triangle"
    },
    "id": "53489e7b-ca23-4aec-a544-0c27f40387c8",
    "line_color": "#e7e7f2ff",
    "line_width": 5,
    "src": {
      "auto_location": false,
      "id": "fc2f6c60-5831-49b5-bc09-2e553c8cd137",
      "rel_location": {
        "x": 1,
        "y": 1
      },
      "tip": "none"
    },
    "state": "normal",
    "type": "curve",
    "widget_type": "Connector"
  }
]

Get Single Connector

Returns a single connector by ID.

GET /api/v1/canvases/:canvas_id/connectors/:connector_id

Path parameters:

canvas_id (uuid, required) -- ID of the canvas
connector_id (uuid, required) -- ID of the connector

Query parameters:

subscribe (boolean, optional) -- Enable streaming updates

Example request:

curl -H "Private-Token: YOUR_TOKEN" \
  https://canvus.example.com/api/v1/canvases/09348962-32aa-480d-b3d6-cacef4030ac2/connectors/53489e7b-ca23-4aec-a544-0c27f40387c8

Example response:

{
  "dst": {
    "auto_location": false,
    "id": "9d928b20-2886-4c23-b86f-07d5a444ba72",
    "rel_location": {
      "x": 0,
      "y": 0.5
    },
    "tip": "solid-equilateral-triangle"
  },
  "id": "53489e7b-ca23-4aec-a544-0c27f40387c8",
  "line_color": "#e7e7f2ff",
  "line_width": 5,
  "src": {
    "auto_location": false,
    "id": "fc2f6c60-5831-49b5-bc09-2e553c8cd137",
    "rel_location": {
      "x": 1,
      "y": 1
    },
    "tip": "none"
  },
  "state": "normal",
  "type": "curve",
  "widget_type": "Connector"
}

Create Connector

Creates a new connector between two widgets. Both src and dst must reference existing widgets on the same canvas.

POST /api/v1/canvases/:canvas_id/connectors

Path parameters:

canvas_id (uuid, required) -- ID of the canvas

Body parameters (JSON):

src (object, required) -- Source endpoint. Must include at minimum:
id (uuid, required) -- Widget ID to connect from
rel_location (object, optional) -- Attachment point as {"x": float, "y": float}
auto_location (boolean, optional) -- Let the server pick the best point
tip (string, optional) -- Arrowhead style: "none" or "solid-equilateral-triangle"
dst (object, required) -- Destination endpoint. Same structure as src.
type (string, optional) -- Line shape: "curve", "straight", or "right-angle". Defaults to "curve".
line_color (string, optional) -- RGBA hex color string.
line_width (number, optional) -- Line thickness in pixels.

Example request:

curl -X POST \
  -H "Private-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "src": {
      "id": "fc2f6c60-5831-49b5-bc09-2e553c8cd137",
      "rel_location": {"x": 1, "y": 0.5},
      "auto_location": false,
      "tip": "none"
    },
    "dst": {
      "id": "9d928b20-2886-4c23-b86f-07d5a444ba72",
      "rel_location": {"x": 0, "y": 0.5},
      "auto_location": false,
      "tip": "solid-equilateral-triangle"
    },
    "type": "curve",
    "line_color": "#3498dbff",
    "line_width": 4
  }' \
  https://canvus.example.com/api/v1/canvases/09348962-32aa-480d-b3d6-cacef4030ac2/connectors

Example response:

{
  "dst": {
    "auto_location": false,
    "id": "9d928b20-2886-4c23-b86f-07d5a444ba72",
    "rel_location": {
      "x": 0,
      "y": 0.5
    },
    "tip": "solid-equilateral-triangle"
  },
  "id": "b17a3e44-91cf-4d02-a3f8-72e6c4109d55",
  "line_color": "#3498dbff",
  "line_width": 4,
  "src": {
    "auto_location": false,
    "id": "fc2f6c60-5831-49b5-bc09-2e553c8cd137",
    "rel_location": {
      "x": 1,
      "y": 0.5
    },
    "tip": "none"
  },
  "state": "normal",
  "type": "curve",
  "widget_type": "Connector"
}

Update Connector

Updates one or more properties of an existing connector. Only include the fields you want to change.

PATCH /api/v1/canvases/:canvas_id/connectors/:connector_id

Path parameters:

canvas_id (uuid, required) -- ID of the canvas
connector_id (uuid, required) -- ID of the connector to update

Body parameters (JSON):

src (object, optional) -- Updated source endpoint (partial updates within the object are supported).
dst (object, optional) -- Updated destination endpoint.
type (string, optional) -- New line shape.
line_color (string, optional) -- New color.
line_width (number, optional) -- New thickness.

Example request -- change color and width:

curl -X PATCH \
  -H "Private-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"line_color": "#e74c3cff", "line_width": 8}' \
  https://canvus.example.com/api/v1/canvases/09348962-32aa-480d-b3d6-cacef4030ac2/connectors/53489e7b-ca23-4aec-a544-0c27f40387c8

Example response:

{
  "dst": {
    "auto_location": false,
    "id": "9d928b20-2886-4c23-b86f-07d5a444ba72",
    "rel_location": {
      "x": 0,
      "y": 0.5
    },
    "tip": "solid-equilateral-triangle"
  },
  "id": "53489e7b-ca23-4aec-a544-0c27f40387c8",
  "line_color": "#e74c3cff",
  "line_width": 8,
  "src": {
    "auto_location": false,
    "id": "fc2f6c60-5831-49b5-bc09-2e553c8cd137",
    "rel_location": {
      "x": 1,
      "y": 1
    },
    "tip": "none"
  },
  "state": "normal",
  "type": "curve",
  "widget_type": "Connector"
}

Example request -- add an arrowhead to the source:

curl -X PATCH \
  -H "Private-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"src": {"tip": "solid-equilateral-triangle"}}' \
  https://canvus.example.com/api/v1/canvases/09348962-32aa-480d-b3d6-cacef4030ac2/connectors/53489e7b-ca23-4aec-a544-0c27f40387c8

Delete Connector

Permanently removes a connector from the canvas. The widgets it was connecting are not affected.

DELETE /api/v1/canvases/:canvas_id/connectors/:connector_id

Path parameters:

canvas_id (uuid, required) -- ID of the canvas
connector_id (uuid, required) -- ID of the connector to delete

Example request:

curl -X DELETE \
  -H "Private-Token: YOUR_TOKEN" \
  https://canvus.example.com/api/v1/canvases/09348962-32aa-480d-b3d6-cacef4030ac2/connectors/53489e7b-ca23-4aec-a544-0c27f40387c8

A successful deletion returns an empty response with HTTP status 200.

Streaming

All GET endpoints support the ?subscribe query parameter for real-time updates. See Streaming for details.

curl -H "Private-Token: YOUR_TOKEN" \
  "https://canvus.example.com/api/v1/canvases/09348962-32aa-480d-b3d6-cacef4030ac2/connectors?subscribe"

Error Cases

400 Bad Request -- Invalid JSON, missing required src or dst on creation, or referenced widget IDs that do not exist on the canvas.
401 Unauthorized -- Missing or invalid Private-Token header.
403 Forbidden -- View-only users cannot create, update, or delete connectors.
404 Not Found -- The canvas ID or connector ID does not exist.

Notes on Connector Behavior

Deleting a widget that is referenced by a connector's src or dst will also delete the connector.
The rel_location coordinates are normalized to the widget's bounding box. {"x": 0, "y": 0} is the top-left corner; {"x": 1, "y": 1} is the bottom-right corner.
Setting auto_location to true on an endpoint causes the server to ignore rel_location and compute the visually optimal attachment point based on the relative positions of the two connected widgets.