# Variables

Store reusable configuration values and credentials as Variables, then reference their keys in supported text fields.

## What are Variables

Variables supply values at runtime for:

* Assistant instructions
* MCP server URLs and headers
* Any other templated text field that supports dynamic evaluation

***

## How it works

Variables can be stored at Organisation or Project scope. The voice runtime currently loads Project-scoped Variables for the Assistant's Project; it does not automatically fall back to Organisation-scoped Variables. Create the Variables needed by an Assistant in its Project.

### Resolution flow

<Mermaid chart={`flowchart LR
    A[Text field with variable syntax] --> B{Variable key lookup}
    B --> C{Project Variable exists?}
    C -->|Yes| D[Use Project Variable value]
    C -->|No| G[No Project Variable value]`} />

For a Project Variable reference, the runtime looks up the key in the Assistant's Project and replaces the placeholder with its value. It does not load an Organisation Variable as a fallback.

Call-specific sources can override Project Variables. See [Data Injection](/docs/data-injection#variable-resolution-priority) for the full priority order. If no source supplies a value, the placeholder resolves to an empty string.

### Variable syntax

Use single or double curly braces with the Variable key to reference a Variable in any supported text field. Both `{key}` and `{{key}}` are accepted:

```
{ key }
```

**Example in Assistant instructions:**

```
You are a customer support agent for { companyName }.
```

If you have a Variable with key `companyName`:

```json
{
  "key": "companyName",
  "value": "Acme Corporation",
  "...": "other fields"
}
```

It will be replaced at runtime:

```
You are a customer support agent for Acme Corporation.
```

***

## Variable entity structure

| Field       | Type                        | Required | Description                                         |
| ----------- | --------------------------- | -------- | --------------------------------------------------- |
| `key`       | string                      | Yes        | The reference name used in `{ key }` syntax         |
| `value`     | JSON value                  | Yes        | The value to inject at runtime                      |
| `isSecret`  | boolean                     | No       | When `true`, the value is treated as sensitive data |
| `projectId` | UUID                        | No       | Links to a Project for Project-scoped Variables     |

***

## Creating Variables

The request paths below are relative to the Data API server URL in the [API reference](/api), which includes `/data_next`. See [Authentication](/docs/authentication) for API key scopes.

### Organisation-level Variable

Use an organization-scoped API key and omit `projectId` to create an Organisation Variable. For use in a voice Assistant, create a Project-scoped Variable instead:

```http
POST /core/variables
Content-Type: application/json
Authorization: Bearer <your-api-token>

{
  "key": "companyName",
  "value": "Acme Corporation",
  "isSecret": false
}
```

### Project-level Variable

Create a Variable scoped to the Assistant's Project:

```http
POST /core/variables
Content-Type: application/json
Authorization: Bearer <your-api-token>

{
  "key": "companyName",
  "value": "Acme Europe Division",
  "isSecret": false,
  "projectId": "b2c3d4e5-f6a7-8901-bcde-f23456789012"
}
```

### Response

The Organisation-level example returns:

```json
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "key": "companyName",
  "value": "Acme Corporation",
  "isSecret": false,
  "organizationId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "projectId": null
}
```

***

## Working with secrets

For sensitive data like API keys, passwords, or tokens, set `isSecret` to `true`:

```http
POST /core/variables
Content-Type: application/json
Authorization: Bearer <your-api-token>

{
  "key": "externalApiKey",
  "value": "sk-live-abc123xyz789",
  "isSecret": true,
  "projectId": "b2c3d4e5-f6a7-8901-bcde-f23456789012"
}
```

Secret Variables:

* Can be resolved in supported text fields such as HTTP and MCP headers
* Are excluded from the rendering context used for SMS bodies and email subjects and bodies

The `isSecret` flag marks a value as sensitive; it is not a guarantee of field-level encryption or a reason to include credentials in spoken prompts.

***

## Use cases

### MCP server configuration

Store MCP server credentials as Secret Variables:

```http
POST /core/variables
Content-Type: application/json
Authorization: Bearer <your-api-token>

{
  "key": "mcpApiToken",
  "value": "abc123xyz789",
  "isSecret": true,
  "projectId": "b2c3d4e5-f6a7-8901-bcde-f23456789012"
}
```

Reference the Secret Variable in your MCP configuration's authorization header:

```http
POST /ai/mcp
Content-Type: application/json
Authorization: Bearer <your-api-token>

{
  "name": "Example MCP",
  "url": "https://api.example.com/mcp",
  "headers": {
    "Authorization": "Bearer { mcpApiToken }"
  }
}
```

### Assistant instructions

Inject dynamic values into Assistant prompts:

```
You are { assistantPersona }, a helpful assistant for { companyName }.
When users ask about pricing, refer them to { pricingUrl }.
Current promotion code: { promoCode }
```

***

## Constraints

* **Unique keys**: Variable keys must be unique within the same scope (Organisation or Project). Attempting to create a duplicate key will return a `DUPLICATE_SECRET_KEY` error.

* **Voice-call scope**: The voice runtime loads Project Variables. Injected data and startup-request data can override ordinary Project Variable values for a call.

* **Value types**: Values are stored as JSON. Strings are substituted directly; numbers, booleans, arrays and objects are rendered as JSON text when inserted into a template.

* **Key naming**: Choose descriptive, consistent key names. Keys are case-sensitive, so `apiKey` and `ApiKey` are treated as different Variables.
