Skip to content

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.

Authentication

All endpoints require authentication via the Private-Token header or a CanvusSession cookie, unless the canvas has link sharing enabled (View or Edit permission). Write operations (POST, PATCH, DELETE) require edit access. View-only users receive 403 Forbidden on any write attempt.

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 canvas coordinates, not screen 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), and the point must lie on the widget's edge: at least one of x or y must be 0 or 1. For example, {"x": 0.5, "y": 0} places the endpoint at the top-center of the widget. An interior point such as {"x": 0.5, "y": 0.5} returns 400 Bad Request.
  • auto_location (boolean) -- When true, the Canvus client that displays or edits the canvas picks the attachment point from the two widgets' positions and stores it in rel_location. The server itself does not compute it. When false, the connector uses the rel_location value.
  • tip (string) -- Arrowhead style at this endpoint. Known values: "none", "solid-equilateral-triangle".

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"

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 (flag, optional) -- Enable streaming updates. The parameter takes no value; its presence alone turns streaming on, so ?subscribe=false also streams. 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 (flag, optional) -- Enable streaming updates. The parameter takes no value; its presence alone turns streaming on, so ?subscribe=false also streams.

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 Canvus client pick the attachment 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 canvas coordinates.

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.

Error responses

  • 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.

Current behavior

  • An invalid or expired token returns 403 Forbidden, not 401. See Current behavior.
  • Only "curve" is currently supported. Other type values are accepted but ignored on create and update, and the connector stays a curve.
  • Deleting a widget does not yet delete the connectors attached to it. The server removes them later, the next time the canvas is loaded; until then they are still returned. Delete them yourself if you need them gone immediately.

These are being corrected.

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 lets the Canvus client choose the attachment point based on the relative positions of the two connected widgets. The server stores the flag but does not calculate the point, and any rel_location you send is still validated.