Variables

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

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

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.

If only type is supplied, Arcweave reuses and normalizes the current value when it is compatible with the new type.

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

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.