Connections

Connection endpoints create, retrieve, update, and delete connections between board items.

Endpoints

Create connection # POST/api/v1/{hash}/connection

Request

HTTP

POST /api/v1/{hash}/connection

curl

curl --request POST \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data @payload.json \
  "https://arcweave.com/api/v1/PROJECT_HASH/connection"

{
  "boardId": "b1",
  "sourceid": "e2",
  "sourceType": "elements",
  "targetid": "e1",
  "targetType": "elements",
  "label": "<p>Continue</p>",
  "labelLocation": 0.25,
  "labelWidth": 180,
  "theme": "default",
  "type": "Bezier"
}

Request fields:

Property	Required	Type	Description
boardId	Yes	String	Board containing the connection.
sourceid	Yes	String	Source item ID.
sourceType	Yes	String	elements or conditions.
targetid	Yes	String	Target item ID.
targetType	Yes	String	elements, branches, or jumpers.
label	No	String, null, or localized map	Connection label. Defaults to no label.
labelLocation	No	Number	Relative label position from 0 to 1. Defaults to 0.5.
labelWidth	No	Number	Positive label width.
sourceFace	No	String or null	left, right, top, or bottom. Omit or use null to leave the face unset.
targetFace	No	String or null	left, right, top, or bottom. Omit or use null to leave the face unset.
theme	No	String	One of the color themes. Defaults to default.
type	No	String	Straight, Bezier, or Flowchart (case-sensitive). Defaults to Bezier.

boardId must identify a regular board, not a folder. The source and target must exist on that board; a condition belongs to the board that contains its branch. A condition has a single output connection: if it already has one, delete that connection or update its target instead of creating another connection from the condition.

Provide label as valid rich text HTML. Labels support Arcscript code blocks, but not blockquotes or inline code. Code blocks must contain valid Arcscript, and the variables, variable attributes, and elements they reference must exist. Otherwise, the request returns 400 Bad Request with the title Bad Request - invalid Arcscript and an error for each invalid label path.

A string or null updates only the project's main language. Locale maps update only the supplied, already configured languages; see Localized content for examples and error handling.

Response

Returns 201 Created with the generated resource ID and project version data:

{
  "version": 12,
  "newVersion": 13,
  "versionTime": ["1720788000", "123456"],
  "id": "65139ea3-331f-4b25-88b4-ea7a65ff106c"
}

Get connection # GET/api/v1/{hash}/connection/{connectionID}

Request

HTTP

GET /api/v1/{hash}/connection/{connectionID}

curl

curl --request GET \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Accept: application/json" \
  "https://arcweave.com/api/v1/PROJECT_HASH/connection/{connectionID}"

Response

Returns 200 OK.

{
  "id": "con2",
  "boardId": "b1",
  "sourceid": "e2",
  "targetid": "e1",
  "sourceType": "elements",
  "targetType": "elements",
  "theme": "default",
  "type": "Bezier",
  "label": {
    "en": {
      "text": "<p>Test label</p><pre><code>custom_b1.board_var_9 == 0</code></pre>"
    }
  }
}

boardId is derived from the board that contains the connection.

Update connection # PATCH/api/v1/{hash}/connection/{connectionID}

Request

HTTP

PATCH /api/v1/{hash}/connection/{connectionID}

curl

curl --request PATCH \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data @payload.json \
  "https://arcweave.com/api/v1/PROJECT_HASH/connection/{connectionID}"

{
  "label": {
    "en": {
      "text": "<p>Updated label</p>"
    }
  },
  "labelLocation": 0.75,
  "labelWidth": 180,
  "theme": "blue",
  "type": "Straight",
  "targetid": "e3",
  "targetType": "elements",
  "sourceFace": "left",
  "targetFace": "right"
}

Request fields:

Property	Required	Type	Description
label	No	String, null, or localized map	Updated label. If omitted, the current value is retained.
labelLocation	No	Number	Relative label position from 0 to 1. Omit to keep the current value.
labelWidth	No	Number or null	Positive label width. Use null to remove the stored width.
theme	No	String	One of the color themes. Omit to keep the current theme.
type	No	String	Straight, Bezier, or Flowchart (case-sensitive). Omit to keep the current type.
sourceid	No	String	New source item ID. Must be sent together with sourceType.
sourceType	No	String	New source type: elements or conditions.
targetid	No	String	New target item ID. Must be sent together with targetType.
targetType	No	String	New target type: elements, branches, or jumpers.
sourceFace	No	String or null	left, right, top, or bottom. Use null to clear; omit to retain.
targetFace	No	String or null	left, right, top, or bottom. Use null to clear; omit to retain.

When changing an endpoint, send its ID and type as a pair. The new source and target must exist on the connection's board and form a valid connection. A condition cannot become the source when it already owns another output connection.

The update must include at least one supported field. The label formatting rules and Arcscript validation also apply to updates.

A string or null updates only the project's main language; locale maps update only the supplied, already configured languages. Path-style fields such as label/fr/text are also supported. See Localized content for examples and error handling.

Response

Returns 200 OK with project version data:

{
  "version": 12,
  "newVersion": 13,
  "versionTime": ["1720788000", "123456"]
}

Delete connection # DELETE/api/v1/{hash}/connection/{connectionID}

Request

HTTP

DELETE /api/v1/{hash}/connection/{connectionID}

curl

curl --request DELETE \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Accept: application/json" \
  "https://arcweave.com/api/v1/PROJECT_HASH/connection/{connectionID}"

Response

Returns 200 OK with project version data:

{
  "version": 12,
  "newVersion": 13,
  "versionTime": ["1720788000", "123456"]
}

Common errors

Status	Meaning
400	Invalid fields, enum, numeric value, label content or Arcscript, incomplete endpoint pair, or a folder boardId.
403	Project permission denied.
404	Project or connection not found.
409	An unknown locale was supplied; the board, source, target, or connection is missing, or an endpoint is on another board; an update would give a condition a second output; or the project changed during Arcscript validation.