Variables

Variable endpoints manage global variables. Use board and component variable attributes for values scoped to those owners.

The REST API has no endpoint that lists variables. To find variable IDs, use the JSON export, whose variables object is keyed by variable ID.

Endpoints

Get variable # GET/api/v1/{hash}/variable/{variableID}

Request

HTTP

GET /api/v1/{hash}/variable/{variableID}

curl

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

Response

Returns 200 OK.

Global variable:

{
  "id": "v2",
  "name": "variable_2",
  "type": "string",
  "value": "test value",
  "cType": "global"
}

Global variables use "cType": "global". Board-scoped values are stored as attributes and use the board attribute endpoints.

The internal root variable container is not exposed and returns 404 Not Found.

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

Request

HTTP

POST /api/v1/{hash}/variable

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/variable"

{
  "name": "door_open",
  "type": "boolean",
  "value": true,
  "index": 0
}

Property	Required	Type	Description
name	Yes	String	Starts with a letter, $, or _; remaining characters may be letters, numbers, or underscores.
type	No	String	string, integer, float, or boolean. Defaults to string.
value	No	Depends on type	Must match the resolved type. Defaults to that type's value listed below.
index	No	Non-negative integer or "-"	Position within the global variable list. Defaults to "-", which appends the variable.

Default values by type

When value is omitted, Arcweave uses the default for the resolved variable type:

Type	Default value
string	""
integer	0
float	0.0
boolean	false

Accepted values by type

Type	Accepted value
string	A JSON string.
integer	An integer, or a string containing an integer such as "42". Stored as a number.
float	A number, or a numeric string such as "0.5". Stored as a number.
boolean	true or false. Strings such as "true" are rejected.

Variable names must be unique among global variables and cannot be Arcscript reserved identifiers such as if, true, or random. The boardId field is not accepted; create a board variable attribute instead.

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 variable # PATCH/api/v1/{hash}/variable/{variableID}

Request

HTTP

PATCH /api/v1/{hash}/variable/{variableID}

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/variable/{variableID}"

{
  "type": "integer",
  "value": "42"
}

Request fields:

Property	Required	Type	Description
type	No	String	string, integer, float, or boolean. If omitted, the current type is retained.
value	No	Type-dependent	Updated value. If omitted, the current value is normalized for any new type.

Only type and value can be updated. Renaming a variable is not supported.

The final value must be an accepted value for the final type. If only type is supplied, Arcweave reuses and normalizes the current value when it is compatible with the new type; for example, 5 can become a float, and "42" can become an integer. Otherwise, the request returns 400 Bad Request; send a value for the new type in the same request.

Response

Returns 200 OK with project version data:

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

Reorder variable # PATCH/api/v1/{hash}/variable/{variableID}/index

Request

HTTP

PATCH /api/v1/{hash}/variable/{variableID}/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/variable/{variableID}/index"

{
  "index": 0
}

Request fields:

Property	Required	Type	Description
index	Yes	Non-negative integer	New position within the global variable list.

This reorders a global variable. An index past the end of the list moves the variable to the last position. Reorder board and component variable attributes through their respective attribute endpoints.

Response

Returns 200 OK with project version data:

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

Delete variable # DELETE/api/v1/{hash}/variable/{variableID}

Request

HTTP

DELETE /api/v1/{hash}/variable/{variableID}

curl

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

Deleting a variable does not update Arcscript that references it. Review element content, connection labels, and branch conditions that use the variable.

Response

Returns 200 OK with project version data:

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

Common errors

Status	Meaning
400	Invalid name, duplicate name, unsupported type, incompatible value, attempted rename, or invalid index.
403	Project permission denied.
404	Project or variable not found, or an internal root ID was requested.
409	Missing variable or invalid container metadata.