# Branches and conditions

Source: https://docs.arcweave.com/rest-api/branches
Section: REST API
Description: REST API endpoints for branches and branch conditions

Branch endpoints manage branch nodes and their `if`, `else if`, and `else` conditions.

## Condition scripts

Context: Arcweave docs > REST API > Branches and conditions > Condition scripts

A condition `script` is an Arcscript expression, such as `score > 3`, without the `<pre><code>` wrapper used in element content. To reference an element, for example in `visits()`, use the element mention markup shown in the [Get branch](https://docs.arcweave.com/rest-api/branches#get-branch) response. Empty strings are normalized to `null`.

Non-empty scripts must be 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 `conditions.{conditionId}.script` path. These rules apply to every endpoint on this page that accepts a `script`.

The `else` condition is followed when no `if` or `else if` condition is true. Play Mode does not evaluate its script, and the editor does not display one, so omit `script` or use `null` for `else` conditions.

## Endpoints

Context: Arcweave docs > REST API > Branches and conditions > Endpoints

### Branch

Context: Arcweave docs > REST API > Branches and conditions > Endpoints > Branch

### Create branch

Context: Arcweave docs > REST API > Branches and conditions > Endpoints > Create branch

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

**Request**

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

```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/branch"
```

```json
{
  "boardId": "b1",
  "x": 650,
  "y": 700,
  "theme": "blue",
  "conditions": {
    "ifCondition": {
      "script": "score > 3"
    },
    "elseIfConditions": [
      {
        "script": "lives > 0"
      }
    ],
    "elseCondition": {
      "script": null
    }
  }
}
```

| Property     | Required | Type                          | Description                                                                           |
| ------------ | -------- | ----------------------------- | ------------------------------------------------------------------------------------- |
| `boardId`    | Yes      | String                        | Board that will contain the branch.                                                   |
| `x`          | Yes      | Number                        | Horizontal board coordinate.                                                          |
| `y`          | Yes      | Number                        | Vertical board coordinate.                                                            |
| `theme`      | No       | String                        | One of the [color themes](https://docs.arcweave.com/rest-api/overview#color-themes). Defaults to `default`.    |
| `conditions` | No       | Object                        | Initial condition definitions. Defaults to an `if` condition with a `null` script.    |
| `index`      | No       | Non-negative integer or `"-"` | Position within the board's branch list. Defaults to `"-"`, which appends the branch. |

`boardId` must identify a regular board, not a folder. Branches use a fixed `288` by `53` footprint and must fit inside the `40000` by `40000` board canvas. `x` must be between `0` and `39712`, and `y` must be between `0` and `39947`.

Every branch receives an `if` condition, even when `conditions.ifCondition` is omitted. On create, condition objects may contain only `script`; condition IDs and outputs are server-managed. Scripts follow the [condition script rules](https://docs.arcweave.com/rest-api/branches#condition-scripts).

**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 branch

Context: Arcweave docs > REST API > Branches and conditions > Endpoints > Get branch

`GET /api/v1/{hash}/branch/{branchID}`

**Request**

```http title="HTTP"
GET /api/v1/{hash}/branch/{branchID}
```

```bash title="curl"
curl --request GET \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Accept: application/json" \
  "https://arcweave.com/api/v1/PROJECT_HASH/branch/{branchID}"
```

**Response**

Returns `200 OK`.

The response expands condition IDs into embedded objects:

```json
{
  "id": "br2",
  "boardId": "b1",
  "x": 500,
  "y": 500,
  "theme": "default",
  "conditions": {
    "ifCondition": {
      "id": "cond3",
      "output": "condCon3",
      "script": "variable_1 > 10"
    },
    "elseIfConditions": [
      {
        "id": "cond4",
        "output": "condCon4",
        "script": null
      },
      {
        "id": "cond5",
        "output": "condCon5",
        "script": null
      },
      {
        "id": "cond6",
        "output": null,
        "script": "visits(<span class=\"mention-element mention\" data-id=\"mentioned_e\" data-label=\"Mentioned element title\" data-type=\"element\">mentioned_element_title</span>)"
      }
    ],
    "elseCondition": {
      "id": "cond7",
      "output": null,
      "script": null
    }
  }
}
```

Each condition's `output` is the ID of its outgoing connection, or `null` when it has none. `elseIfConditions` and `elseCondition` can be omitted when the branch has no such conditions.

### Update branch and its condition set

Context: Arcweave docs > REST API > Branches and conditions > Endpoints > Update branch and its condition set

`PATCH /api/v1/{hash}/branch/{branchID}`

**Request**

```http title="HTTP"
PATCH /api/v1/{hash}/branch/{branchID}
```

```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/branch/{branchID}"
```

```json
{
  "x": 725,
  "theme": "red",
  "conditions": {
    "ifCondition": {
      "script": "score > 5"
    },
    "elseIfConditions": [
      {
        "id": "cond5",
        "script": "lives > 1"
      },
      {
        "script": "lives == 1"
      },
      {
        "id": "cond4"
      }
    ],
    "elseCondition": null
  }
}
```

Request fields:

| Property     | Required | Type   | Description                                                                                 |
| ------------ | -------- | ------ | ------------------------------------------------------------------------------------------- |
| `theme`      | No       | String | One of the [color themes](https://docs.arcweave.com/rest-api/overview#color-themes). Omit to keep the current theme. |
| `x`          | No       | Number | Updated horizontal coordinate. If omitted, the current value is retained.                   |
| `y`          | No       | Number | Updated vertical coordinate. If omitted, the current value is retained.                     |
| `conditions` | No       | Object | Desired final condition set. If omitted, conditions remain unchanged.                       |

Supported root fields are `theme`, `x`, `y`, and `conditions`.

Coordinate updates must keep the complete fixed-size branch inside the `40000` by `40000` board canvas.

The condition payload represents the desired final state. Omitted keys leave those conditions unchanged:

- `ifCondition` updates the existing `if` condition. If its ID is included, it must match the branch's `if` condition.
- An `elseCondition` object creates or updates the `else` condition. `null` deletes it. If its ID is included, it must match the branch's existing `else` condition.
- `elseIfConditions` is the final ordered list.
- Existing `else if` conditions are referenced by ID; each ID must belong to this branch and appear only once.
- Entries without an ID create new conditions.
- Existing `else if` conditions omitted from the array are deleted.
- Deleting an `else` or `else if` condition through this update also deletes any outgoing connections from that condition.
- `output` is internal and cannot be supplied.

Scripts follow the [condition script rules](https://docs.arcweave.com/rest-api/branches#condition-scripts).

**Response**

Returns `200 OK` with project version data:

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

### Delete branch

Context: Arcweave docs > REST API > Branches and conditions > Endpoints > Delete branch

`DELETE /api/v1/{hash}/branch/{branchID}`

**Request**

```http title="HTTP"
DELETE /api/v1/{hash}/branch/{branchID}
```

```bash title="curl"
curl --request DELETE \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Accept: application/json" \
  "https://arcweave.com/api/v1/PROJECT_HASH/branch/{branchID}"
```

Deleting a branch also deletes its owned conditions, connections targeting the branch, and outgoing connections from its conditions.

**Response**

Returns `200 OK` with project version data:

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

### If condition

Context: Arcweave docs > REST API > Branches and conditions > Endpoints > If condition

### Update the if condition

Context: Arcweave docs > REST API > Branches and conditions > Endpoints > Update the if condition

`PATCH /api/v1/{hash}/branch/{branchID}/if-condition`

**Request**

```http title="HTTP"
PATCH /api/v1/{hash}/branch/{branchID}/if-condition
```

```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/branch/{branchID}/if-condition"
```

```json
{
  "script": "score >= 10"
}
```

Request fields:

| Property | Required | Type             | Description                                                       |
| -------- | -------- | ---------------- | ----------------------------------------------------------------- |
| `script` | Yes      | String or `null` | Updated condition script. Empty strings are normalized to `null`. |

The script follows the [condition script rules](https://docs.arcweave.com/rest-api/branches#condition-scripts).

**Response**

Returns `200 OK` with project version data:

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

### Else-if conditions

Context: Arcweave docs > REST API > Branches and conditions > Endpoints > Else-if conditions

### Create else-if condition

Context: Arcweave docs > REST API > Branches and conditions > Endpoints > Create else-if condition

`POST /api/v1/{hash}/branch/{branchID}/else-if-condition`

**Request**

```http title="HTTP"
POST /api/v1/{hash}/branch/{branchID}/else-if-condition
```

```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/branch/{branchID}/else-if-condition"
```

```json
{
  "script": "lives > 0"
}
```

Request fields:

| Property | Required | Type             | Description                                                      |
| -------- | -------- | ---------------- | ---------------------------------------------------------------- |
| `script` | No       | String or `null` | Condition script. Defaults to `null`; the condition is appended. |

`script` is optional and may be `null`. The new condition is appended; use the reorder endpoint afterward to move it.

**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"
}
```

### Update else-if condition

Context: Arcweave docs > REST API > Branches and conditions > Endpoints > Update else-if condition

`PATCH /api/v1/{hash}/branch/{branchID}/else-if-condition/{conditionID}`

**Request**

```http title="HTTP"
PATCH /api/v1/{hash}/branch/{branchID}/else-if-condition/{conditionID}
```

```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/branch/{branchID}/else-if-condition/{conditionID}"
```

```json
{
  "script": "lives > 1"
}
```

Request fields:

| Property | Required | Type             | Description                                                       |
| -------- | -------- | ---------------- | ----------------------------------------------------------------- |
| `script` | Yes      | String or `null` | Updated condition script. Empty strings are normalized to `null`. |

**Response**

Returns `200 OK` with project version data:

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

### Reorder else-if condition

Context: Arcweave docs > REST API > Branches and conditions > Endpoints > Reorder else-if condition

`PATCH /api/v1/{hash}/branch/{branchID}/else-if-condition/{conditionID}/index`

**Request**

```http title="HTTP"
PATCH /api/v1/{hash}/branch/{branchID}/else-if-condition/{conditionID}/index
```

```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/branch/{branchID}/else-if-condition/{conditionID}/index"
```

```json
{
  "index": 0
}
```

Request fields:

| Property | Required | Type                 | Description                                                                                       |
| -------- | -------- | -------------------- | ------------------------------------------------------------------------------------------------- |
| `index`  | Yes      | Non-negative integer | New position among the branch's `else if` conditions, where `0` is the first `else if` condition. |

An index past the end of the list moves the condition to the last position.

**Response**

Returns `200 OK` with project version data:

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

### Delete else-if condition

Context: Arcweave docs > REST API > Branches and conditions > Endpoints > Delete else-if condition

`DELETE /api/v1/{hash}/branch/{branchID}/else-if-condition/{conditionID}`

**Request**

```http title="HTTP"
DELETE /api/v1/{hash}/branch/{branchID}/else-if-condition/{conditionID}
```

```bash title="curl"
curl --request DELETE \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Accept: application/json" \
  "https://arcweave.com/api/v1/PROJECT_HASH/branch/{branchID}/else-if-condition/{conditionID}"
```

Deleting an `else if` condition also deletes any outgoing connections from it.

Condition endpoints enforce ownership: a condition can only be changed through the branch that owns it.

**Response**

Returns `200 OK` with project version data:

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

### Else condition

Context: Arcweave docs > REST API > Branches and conditions > Endpoints > Else condition

### Create the else condition

Context: Arcweave docs > REST API > Branches and conditions > Endpoints > Create the else condition

`POST /api/v1/{hash}/branch/{branchID}/else-condition`

**Request**

```http title="HTTP"
POST /api/v1/{hash}/branch/{branchID}/else-condition
```

```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/branch/{branchID}/else-condition"
```

```json
{}
```

Request fields:

| Property | Required | Type             | Description                           |
| -------- | -------- | ---------------- | ------------------------------------- |
| `script` | No       | String or `null` | Condition script. Defaults to `null`. |

Only one `else` condition can exist. Creating another returns `409 Conflict`. Play Mode does not evaluate an `else` script; see [Condition scripts](https://docs.arcweave.com/rest-api/branches#condition-scripts).

**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"
}
```

### Update the else condition

Context: Arcweave docs > REST API > Branches and conditions > Endpoints > Update the else condition

`PATCH /api/v1/{hash}/branch/{branchID}/else-condition`

**Request**

```http title="HTTP"
PATCH /api/v1/{hash}/branch/{branchID}/else-condition
```

```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/branch/{branchID}/else-condition"
```

```json
{
  "script": null
}
```

Request fields:

| Property | Required | Type             | Description                                                       |
| -------- | -------- | ---------------- | ----------------------------------------------------------------- |
| `script` | Yes      | String or `null` | Updated condition script. Empty strings are normalized to `null`. |

**Response**

Returns `200 OK` with project version data:

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

### Delete the else condition

Context: Arcweave docs > REST API > Branches and conditions > Endpoints > Delete the else condition

`DELETE /api/v1/{hash}/branch/{branchID}/else-condition`

**Request**

```http title="HTTP"
DELETE /api/v1/{hash}/branch/{branchID}/else-condition
```

```bash title="curl"
curl --request DELETE \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Accept: application/json" \
  "https://arcweave.com/api/v1/PROJECT_HASH/branch/{branchID}/else-condition"
```

Deleting the `else` condition also deletes any outgoing connections from it.

**Response**

Returns `200 OK` with project version data:

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

## Common errors

Context: Arcweave docs > REST API > Branches and conditions > Common errors

| Status | Meaning                                                                                                                                                                                |
| ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | Invalid payload, internal condition field supplied, condition ID that does not belong to the branch, empty update, invalid index, invalid Arcscript, or `boardId` identifies a folder. |
| `403`  | Project permission denied.                                                                                                                                                             |
| `404`  | Project, branch, or branch-owned condition not found.                                                                                                                                  |
| `409`  | Missing board/branch, duplicate `else`, stale condition ownership/order snapshot, or the project changed while scripts were validated.                                                 |