# Render Variables API

Contents

* [Render Variables API](https://docs.hostedgraphite.com/api-guides/render-variables-api)
  * [Creating a variable](#creating-a-variable)
  * [Updating a variable](#updating-a-variable)
  * [Search variables](#search-variables)
  * [Get variable values](#get-variable-values)
  * [Delete a variable](#delete-a-variable)
  * [Graphing with render variables](#graphing-with-render-variables)

Render Variables provide versatility when constructing metric queries. Instead of hard-coding full metric names, use variables as placeholders to dynamically build your queries. This is similar, but not the same as the primary dashboard’s built-in template variables.

**NOTE**: we advise against using render variables in alert queries.

### [Creating a variable](#creating-a-variable)

<mark style="color:green;">`POST`</mark> `/v1/variables/<var-name>/`

Replace \<var-name> with the name you want to give the variable. Place your variable values in a JSON file and include it in the POST request. A variable name is required, however the values can be empty.

{% tabs %}
{% tab title="201" %}
Created { "url": "/v1/variables//" }
{% endtab %}

{% tab title="400" %}
Bad Request JSON could be incorrectly formatted or the variable name already exists
{% endtab %}
{% endtabs %}

**Example variable values:**

```json
{
  "values": [
    "foobar",
    "foo",
    "bar",
    "baz"
  ]
}
```

**Curl example:**

```bash
curl -X POST "https://YOUR-API-KEY@api.hostedgraphite.com/v1/variables/<var-name>/" -d @values.json
```

Make sure to include the forward slash character at the end of the request.

***

### [Updating a variable](#updating-a-variable)

<mark style="color:orange;">`PUT`</mark> `/v1/variables/<var-name>/`

Overwrites the values for an existing variable

{% tabs %}
{% tab title="200: OK {  "url": "/v1/variables/<var-name>/" }" %}

{% endtab %}

{% tab title="400: Bad Request JSON could be incorrectly formatted" %}

{% endtab %}

{% tab title="404: Not Found " %}

{% endtab %}
{% endtabs %}

**Curl example:**

```bash
curl -X PUT "https://<apikey>@api.hostedgraphite.com/v1/variables/<var-name>/" -d @values.json
```

***

### [Search variables](#search-variables)

<mark style="color:blue;">`GET`</mark> `/v1/variables/?query=`

A “contains” query that will return a JSON object with the name and path of variables that contain the search term. To list all variables, leave the query empty.

#### Path Parameters

| Name  | Type   | Description |
| ----- | ------ | ----------- |
| query | String |             |

{% tabs %}
{% tab title="200: OK {   "variables" : \[     {       "name" : "foo",       "url" : "/v1/variables/foo/"     },     {       "name" : "bar",       "url" : "/v1/variables/bar/"     }   ] }" %}

{% endtab %}
{% endtabs %}

**Curl example:**

```bash
curl -X GET "https://<apikey>@api.hostedgraphite.com/v1/variables/?query="
```

If you have no variables or there are no variables that match your query you will be returned with an empty object:

```json
{
  "variables": []
}
```

***

### [Get variable values](#get-variable-values)

<mark style="color:blue;">`GET`</mark> `/v1/variables/<var-name>/`

Returns a JSON object with the values assigned to \<var-name>

{% tabs %}
{% tab title="200: OK {   "values": \[     "foobar",     "foo",     "bar",     "baz"   ] }" %}

{% endtab %}

{% tab title="404: Not Found " %}

{% endtab %}
{% endtabs %}

**Curl example:**

```bash
curl -X GET "https://<apikey>@api.hostedgraphite.com/v1/variables/<var-name>/"
```

***

### [Delete a variable](#delete-a-variable)

<mark style="color:red;">`DELETE`</mark> `/v1/variables/<var-name>/`

{% tabs %}
{% tab title="200: OK " %}

{% endtab %}

{% tab title="404: Not Found " %}

{% endtab %}
{% endtabs %}

**Curl example:**

```bash
curl -X DELETE "https://<apikey>@api.hostedgraphite.com/v1/variables/<var-name>/"
```

***

### [Graphing with render variables](#graphing-with-render-variables)

This cannot be done with the simple query builder, you must toggle the edit mode to the free-text mode.

Refer to a render variable by including the variable name enclosed in angled brackets in your metric query: **\<variable-name>**

**Using dashboard templates within render variables**

You can place template variables within render variables by surrounding them with curly brackets:

```bash
$foo.<{$foo}_metric>.bar
```