# Variables

Source: https://docs.arcweave.com/rest-api/variables
Section: REST API
Description: REST API endpoints for global variables

Variable endpoints manage global variables. Use [board and component variable attributes](https://docs.arcweave.com/rest-api/attributes#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](https://docs.arcweave.com/rest-api/exports#json-export), whose `variables` object is keyed by variable ID.

## Endpoints

Context: Arcweave docs > REST API > Variables > Endpoints

### Get variable

Context: Arcweave docs > REST API > Variables > Endpoints > Get variable

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

**Request**

```http title="HTTP"
GET /api/v1/{hash}/variable/{variableID}
```

```bash title="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:

```json
{
  "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](https://docs.arcweave.com/rest-api/attributes#get-board-attributes).

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

### Create variable

Context: Arcweave docs > REST API > Variables > Endpoints > Create variable

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

**Request**

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

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

```json
{
  "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](https://docs.arcweave.com/rest-api/attributes#create-board-attribute) instead.

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

Context: Arcweave docs > REST API > Variables > Endpoints > Update variable

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

**Request**

```http title="HTTP"
PATCH /api/v1/{hash}/variable/{variableID}
```

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

```json
{
  "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](https://docs.arcweave.com/rest-api/variables#create-variable) 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:

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

### Reorder variable

Context: Arcweave docs > REST API > Variables > Endpoints > Reorder variable

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

**Request**

```http title="HTTP"
PATCH /api/v1/{hash}/variable/{variableID}/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/variable/{variableID}/index"
```

```json
{
  "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](https://docs.arcweave.com/rest-api/attributes).

**Response**

Returns `200 OK` with project version data:

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

### Delete variable

Context: Arcweave docs > REST API > Variables > Endpoints > Delete variable

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

**Request**

```http title="HTTP"
DELETE /api/v1/{hash}/variable/{variableID}
```

```bash title="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:

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

## Common errors

Context: Arcweave docs > REST API > Variables > 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.                                                         |