# Connections

Source: https://docs.arcweave.com/rest-api/connections
Section: REST API
Description: REST API endpoints for project connections

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

## Connection paths

Context: Arcweave docs > REST API > Connections > Connection paths

The `type` field sets a connection's style: `Straight`, `Bezier`, or `Flowchart`. Without path geometry, Arcweave routes `Bezier` and `Flowchart` connections automatically. To store a [customized path](https://docs.arcweave.com/project-items/connections#edit-connection-paths), send the geometry field that matches the type:

| Field           | Type   | Description                                                                                                                                                                                         |
| --------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `waypoints`     | Array  | `Flowchart` only. Ordered array of at most 1,000 `{ "x": …, "y": … }` points, in absolute board coordinates.                                                                                        |
| `controlPoints` | Object | `Bezier` only. Object with exactly `source` and `target`, each `{ "x": …, "y": … }`. Each point is an offset, in board units, from the point where the connection attaches to its source or target. |

Each object must contain only numeric `x` and `y`. Every coordinate must be a JSON number between `-40000` and `40000`, inclusive; numeric strings are rejected.

```json
{
  "type": "Flowchart",
  "waypoints": [
    { "x": 480, "y": 180 },
    { "x": 480, "y": 420 }
  ]
}
```

Geometry that doesn't match the effective type is dropped: `Straight` stores neither field, `Flowchart` stores only `waypoints`, and `Bezier` stores only `controlPoints`. Changing a connection to a different type clears its previous path and restores automatic routing, unless the same request supplies geometry for the new type. An empty `waypoints` array also uses automatic routing.

## Endpoints

Context: Arcweave docs > REST API > Connections > Endpoints

### Create connection

Context: Arcweave docs > REST API > Connections > Endpoints > Create connection

`POST /api/v1/{hash}/connection`

**Request**

```http title="HTTP"
POST /api/v1/{hash}/connection
```

```bash title="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"
```

```json
{
  "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](https://docs.arcweave.com/rest-api/localization#write-specific-languages) | 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](https://docs.arcweave.com/rest-api/overview#color-themes). Defaults to `default`. |
| `type`          | No       | String                                                                              | `Straight`, `Bezier`, or `Flowchart` (case-sensitive). Defaults to `Bezier`.       |
| `waypoints`     | No       | Array                                                                               | Customized `Flowchart` path. See [Connection paths](https://docs.arcweave.com/rest-api/connections#connection-paths).            |
| `controlPoints` | No       | Object                                                                              | Customized `Bezier` path. See [Connection paths](https://docs.arcweave.com/rest-api/connections#connection-paths).               |

Omit `waypoints` and `controlPoints` to use automatic routing; `null` is not accepted when creating a connection.

`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](https://docs.arcweave.com/rest-api/rich-text#supported-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](https://docs.arcweave.com/rest-api/localization) for examples and error handling.

**Response**

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

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

### Get connection

Context: Arcweave docs > REST API > Connections > Endpoints > Get connection

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

**Request**

```http title="HTTP"
GET /api/v1/{hash}/connection/{connectionID}
```

```bash title="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`.

```json
{
  "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. A connection with a [customized path](https://docs.arcweave.com/rest-api/connections#connection-paths) also includes `waypoints` or `controlPoints`.

### Update connection

Context: Arcweave docs > REST API > Connections > Endpoints > Update connection

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

**Request**

```http title="HTTP"
PATCH /api/v1/{hash}/connection/{connectionID}
```

```bash title="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}"
```

```json
{
  "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](https://docs.arcweave.com/rest-api/localization#write-specific-languages) | 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](https://docs.arcweave.com/rest-api/overview#color-themes). Omit to keep the current theme. |
| `type`          | No       | String                                                                              | `Straight`, `Bezier`, or `Flowchart` (case-sensitive). Omit to keep the current type.       |
| `waypoints`     | No       | Array or `null`                                                                     | Customized `Flowchart` path. Use `null` to restore automatic routing; omit to retain.       |
| `controlPoints` | No       | Object or `null`                                                                    | Customized `Bezier` path. Use `null` to restore automatic routing; omit to retain.          |
| `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.                   |

Path geometry follows the rules in [Connection paths](https://docs.arcweave.com/rest-api/connections#connection-paths). If `type` is omitted, the geometry must match the connection's current type; otherwise, it is dropped.

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](https://docs.arcweave.com/rest-api/rich-text#supported-html) 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](https://docs.arcweave.com/rest-api/localization) for examples and error handling.

**Response**

Returns `200 OK` with project version data:

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

### Delete connection

Context: Arcweave docs > REST API > Connections > Endpoints > Delete connection

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

**Request**

```http title="HTTP"
DELETE /api/v1/{hash}/connection/{connectionID}
```

```bash title="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:

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

## Common errors

Context: Arcweave docs > REST API > Connections > 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](https://docs.arcweave.com/rest-api/localization#unknown-locale-errors) 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. |