Arcweave Documentation

Appearance

Branches and conditions ​

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

Endpoints ​

Branch ​

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

Request

http
POST /api/v1/{hash}/branch
bash
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
    }
  }
}
PropertyRequiredTypeDescription
boardIdYesStringBoard that will contain the branch.
xYesNumberHorizontal board coordinate.
yYesNumberVertical board coordinate.
themeNoStringOne of the color themes. Defaults to default.
conditionsNoObjectInitial condition definitions. Defaults to an if condition with a null script.
indexNoNon-negative integer or "-"Position within the board's branch list. Defaults to "-", which appends the branch.

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.

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

Request

http
GET /api/v1/{hash}/branch/{branchID}
bash
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(mentioned_element_title)"
      }
    ],
    "elseCondition": {
      "id": "cond7",
      "output": null,
      "script": null
    }
  }
}

Update branch and its condition set # PATCH/api/v1/{hash}/branch/{branchID}

Request

http
PATCH /api/v1/{hash}/branch/{branchID}
bash
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": "updated if condition"
    },
    "elseIfConditions": [
      {
        "id": "cond5",
        "script": "updated else if"
      },
      {
        "script": "brand new else if"
      },
      {
        "id": "cond4"
      }
    ],
    "elseCondition": null
  }
}

Request fields:

PropertyRequiredTypeDescription
themeNoStringOne of the color themes. Omit to keep the current theme.
xNoNumberUpdated horizontal coordinate. If omitted, the current value is retained.
yNoNumberUpdated vertical coordinate. If omitted, the current value is retained.
conditionsNoObjectDesired 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:

  • 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.
  • elseIfConditions is the final ordered list.
  • Existing else if conditions are referenced by ID.
  • Entries without an ID create new conditions.
  • Existing 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.

Response

Returns 200 OK with project version data:

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

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

Request

http
DELETE /api/v1/{hash}/branch/{branchID}
bash
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 ​

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

Request

http
PATCH /api/v1/{hash}/branch/{branchID}/if-condition
bash
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:

PropertyRequiredTypeDescription
scriptYesString or nullUpdated condition script. Empty strings are normalized to null.

script may be a string or null.

Response

Returns 200 OK with project version data:

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

PropertyRequiredTypeDescription
scriptNoString or nullCondition 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 # PATCH/api/v1/{hash}/branch/{branchID}/else-if-condition/{conditionID}

Request

http
PATCH /api/v1/{hash}/branch/{branchID}/else-if-condition/{conditionID}
bash
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:

PropertyRequiredTypeDescription
scriptYesString or nullUpdated 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 # PATCH/api/v1/{hash}/branch/{branchID}/else-if-condition/{conditionID}/index

Request

http
PATCH /api/v1/{hash}/branch/{branchID}/else-if-condition/{conditionID}/index
bash
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:

PropertyRequiredTypeDescription
indexYesNon-negative integerNew position within the branch condition list.

Response

Returns 200 OK with project version data:

json
{
  "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}
bash
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 ​

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

Request

http
POST /api/v1/{hash}/branch/{branchID}/else-condition
bash
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
{
  "script": "fallback branch"
}

Request fields:

PropertyRequiredTypeDescription
scriptNoString or nullCondition script. Defaults to null.

Only one else condition can exist. Creating another returns 409 Conflict.

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

Request

http
PATCH /api/v1/{hash}/branch/{branchID}/else-condition
bash
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": "updated fallback branch"
}

Request fields:

PropertyRequiredTypeDescription
scriptYesString or nullUpdated 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 # DELETE/api/v1/{hash}/branch/{branchID}/else-condition

Request

http
DELETE /api/v1/{hash}/branch/{branchID}/else-condition
bash
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 ​

StatusMeaning
400Invalid payload, internal condition field supplied, empty update, or invalid index.
403Project permission denied.
404Project, branch, or branch-owned condition not found.
409Missing board/branch, duplicate else, or stale condition ownership/order snapshot.