Branches and conditions

Branch endpoints manage branch nodes and their if, else if, and else 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 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

Branch

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

Request

HTTP

POST /api/v1/{hash}/branch

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"

{
  "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. 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.

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 branch # GET/api/v1/{hash}/branch/{branchID}

Request

HTTP

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

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:

{
  "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 # PATCH/api/v1/{hash}/branch/{branchID}

Request

HTTP

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

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

{
  "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. 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.

Response

Returns 200 OK with project version data:

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

Delete branch # DELETE/api/v1/{hash}/branch/{branchID}

Request

HTTP

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

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:

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

If condition

Update the if condition # PATCH/api/v1/{hash}/branch/{branchID}/if-condition

Request

HTTP

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

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"

{
  "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.

Response

Returns 200 OK with project version data:

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

Else-if conditions

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

Request

HTTP

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

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"

{
  "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:

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

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

Request

HTTP

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

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

{
  "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:

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

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

Request

HTTP

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

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"

{
  "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:

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

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

Request

HTTP

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

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:

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

Else condition

Create the else condition # POST/api/v1/{hash}/branch/{branchID}/else-condition

Request

HTTP

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

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"

{}

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.

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

Update the else condition # PATCH/api/v1/{hash}/branch/{branchID}/else-condition

Request

HTTP

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

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"

{
  "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:

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

Delete the else condition # DELETE/api/v1/{hash}/branch/{branchID}/else-condition

Request

HTTP

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

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:

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

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.