> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kadoa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Variables

> Create and manage reusable variables programmatically using the SDK

Variables are key-value pairs that can be referenced in workflow prompts using `@variableKey` syntax. When a workflow runs, Kadoa replaces variable references with the actual values.

For an overview of variable concepts, data types, and usage in prompts, see [Variables](/docs/workflows/variables).

## Prerequisites

* Kadoa account with API key
* SDK installed: `npm install @kadoa/node-sdk`

<Note>
  Variables are currently available in the Node SDK. Python SDK support is coming soon.
</Note>

## Create a Variable

<CodeGroup>
  ```typescript Node SDK theme={null}
  const variable = await client.variable.create({
    key: "target_url",
    value: "https://example.com/products",
    dataType: "STRING",
  });

  console.log("Variable created:", variable.id);
  ```

  ```bash REST API theme={null}
  curl -X POST "https://api.kadoa.com/v4/variables" \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "key": "target_url",
      "value": "https://example.com/products",
      "dataType": "STRING"
    }'
  ```

  ```text MCP Server theme={null}
  > "Create a variable called target_url with value https://example.com/products"
  ```
</CodeGroup>

### Data Types

| Type      | Description          | Example              |
| --------- | -------------------- | -------------------- |
| `STRING`  | Plain text (default) | `"ESG reports"`      |
| `NUMBER`  | Numeric values       | `"25"`               |
| `BOOLEAN` | True/false           | `"true"`             |
| `JSON`    | Structured JSON data | `'{"zip": "10001"}'` |

<Note>
  Values are always passed as strings, regardless of data type.
</Note>

## List Variables

<CodeGroup>
  ```typescript Node SDK theme={null}
  const variables = await client.variable.list();

  for (const variable of variables) {
    console.log(`${variable.key}: ${variable.value} (${variable.dataType})`);
  }
  ```

  ```bash REST API theme={null}
  curl -X GET "https://api.kadoa.com/v4/variables" \
    -H "x-api-key: YOUR_API_KEY"
  ```

  ```text MCP Server theme={null}
  > "List my variables"
  ```
</CodeGroup>

## Get a Variable

<CodeGroup>
  ```typescript Node SDK theme={null}
  const variable = await client.variable.get("VARIABLE_ID");

  console.log(variable.key);
  console.log(variable.value);
  console.log(variable.dataType);
  ```

  ```bash REST API theme={null}
  curl -X GET "https://api.kadoa.com/v4/variables/VARIABLE_ID" \
    -H "x-api-key: YOUR_API_KEY"
  ```

  ```text MCP Server theme={null}
  > "Show me the target_url variable"
  ```
</CodeGroup>

## Update a Variable

Workflows referencing this variable via `@key` will use the new value on their next run.

<CodeGroup>
  ```typescript Node SDK theme={null}
  const updated = await client.variable.update("VARIABLE_ID", {
    value: "https://example.com/products/v2",
  });

  console.log("Variable updated:", updated.key);
  ```

  ```bash REST API theme={null}
  curl -X PATCH "https://api.kadoa.com/v4/variables/VARIABLE_ID" \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "value": "https://example.com/products/v2"
    }'
  ```

  ```text MCP Server theme={null}
  > "Update the target_url variable to https://example.com/products/v2"
  ```
</CodeGroup>

## Delete a Variable

<Warning>
  Deleting a variable is permanent. Workflows referencing it via `@key` will no longer resolve the value.
</Warning>

<CodeGroup>
  ```typescript Node SDK theme={null}
  await client.variable.delete("VARIABLE_ID");
  ```

  ```bash REST API theme={null}
  curl -X DELETE "https://api.kadoa.com/v4/variables/VARIABLE_ID" \
    -H "x-api-key: YOUR_API_KEY"
  ```

  ```text MCP Server theme={null}
  > "Delete the target_url variable"
  ```
</CodeGroup>

## Using Variables in Prompts

Reference variables in workflow prompts with `@variableKey`:

<CodeGroup>
  ```typescript Node SDK theme={null}
  // Create a variable
  await client.variable.create({
    key: "search_term",
    value: "ESG reports",
    dataType: "STRING",
  });

  // Use it in a workflow prompt; Kadoa replaces @search_term at runtime
  const workflow = await client
    .extract({
      urls: ["https://sandbox.kadoa.com/ecommerce"],
      name: "Variable-Driven Search",
      userPrompt: "Search for @search_term and extract all matching results",
      extraction: (builder) =>
        builder
          .entity("Result")
          .field("title", "Result title", "STRING")
          .field("url", "Result URL", "LINK"),
    })
    .create();
  ```
</CodeGroup>