Variables

Store reusable values for your team and reference them in workflow prompts.

Variables are named values you reference in workflow prompts. Use them to run workflows with different input parameters, such as search terms, ZIP codes, or login details.

​

How variables work

When your workflow runs, Kadoa replaces each variable reference with the value you defined.

For example, you create a variable named keywords with the value "ESG reports". This prompt:

- Search for $keywords
- Filter by "2025"
- Extract: data, title, pdfLink

Becomes:

- Search for "ESG reports"
- Filter by "2025"
- Extract: data, title, pdfLink

In the dashboard, you insert a reference by typing $. In the SDK and API, you write @variableKey. See Use a variable in a prompt.

​

Who can use variables

Variables belong to your team.

• All team members can use variables in their workflows.
• Members, Admins, and Owners can create, edit, and delete variables.
• Only Admins and Owners can create, edit, or delete secret variables.
• Viewers and Compliance Officers can see variables but cannot change them.

​

Create a variable

Dashboard

1. Go to Settings > Variables.
2. Select New variable.
3. Enter a unique Key. Keys cannot contain spaces.
4. Select a Type. See Data types.
5. Enter the Value. For an Array, enter one value per line. For a JSON Object, enter valid JSON.
6. Select Create.

For a password or API key, select the Secret type. See Secret variables.

You can also create a variable while you write a prompt. See Use a variable in a prompt.

SDK & API

You need a Kadoa API key and the Node SDK. Install it with npm install @kadoa/node-sdk.

Variables are currently available in the Node SDK. Python SDK support is coming soon.

Node SDK

const variable = await client.variable.create({
  key: "target_url",
  value: "https://example.com/products",
  dataType: "STRING",
});

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

MCP

Ask your AI tool, for example:

> Create a variable called target_url with value https://example.com/products

Your AI tool uses create_variable.

​

Use a variable in a prompt

Dashboard

1. In the setup prompt or in your chat with Kadoa’s agent, type $. A list of available variables opens.
2. Select a variable. It appears as a chip in the prompt and stays linked to the stored variable.

To create a variable without leaving the prompt, select Create variable from the suggestions.

The workflow’s Variables tab lists the variables the workflow uses.

SDK & API

Reference variables in workflow prompts with @variableKey. Kadoa replaces the reference with the value at runtime.

Node SDK

// 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", {
          example: "Annual ESG report",
        })
        .field("url", "Result URL", "LINK", {
          example: "https://example.com/reports/annual-esg-report",
        }),
  })
  .create();

​

Example: location-based search

- Loop through ZIP codes $zipCodes in the location field
- Search for nearby stores within $radius miles
- Extract: store_name, address, phone, hours

Variables: zipCodes: ["10001","10002"], radius: 25

​

Example: authenticated portal access

- Navigate to the login page
- Enter $username in the email field
- Enter $password in the password field
- Click the login button
- Navigate to the reports section
- Extract: report_name, date, download_link

Variables: username: "[e-mail]", password: (Secret)

​

View variables

Dashboard

1. Go to Settings > Variables.

The list shows each variable’s key and value. Secret values are never shown. A count next to each variable shows how many workflows use it. Select the count to see those workflows.

SDK & API

List all variables:

Node SDK

const variables = await client.variable.list();

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

Get one variable by ID:

Node SDK

const variable = await client.variable.get("VARIABLE_ID");

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

MCP

Ask your AI tool, for example:

> List my variables
> Show me the target_url variable

Your AI tool uses list_variables and get_variable.

​

Update a variable

Workflows that reference the variable use the new value on their next run. You cannot change a variable’s type after you create it.

Dashboard

1. Go to Settings > Variables.
2. Select the variable. The dialog lists the workflows that use it.
3. Change the Key or Value.
4. Select Save.

SDK & API

Node SDK

const updated = await client.variable.update("VARIABLE_ID", {
  value: "https://example.com/products/v2",
});

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

MCP

Ask your AI tool, for example:

> Update the target_url variable to https://example.com/products/v2

Your AI tool uses update_variable.

​

Delete a variable

Deleting a variable is permanent. Workflows that reference it no longer resolve the value, and their future runs may fail.

Dashboard

1. Go to Settings > Variables.
2. Select the trash icon next to the variable.
3. Select Delete to confirm.

SDK & API

Node SDK

await client.variable.delete("VARIABLE_ID");

MCP

Ask your AI tool, for example:

> Delete the target_url variable

Your AI tool uses delete_variable. It asks you to confirm before it deletes the variable.

​

Data types

Type	API value	Description	Example
Text	STRING	Plain text. This is the default.	"ESG reports"
Secret	SECRET	Encrypted sensitive values, such as passwords and API keys. See Secret variables.	"••••••••"
Number	NUMBER	Numeric values	"25"
JSON Object	OBJECT	Structured JSON data	{"key": "value"}
Array	ARRAY	Lists of values	["10001", "10002", "10003"]

The API always takes values as strings, regardless of data type.

​

Related

• Secret variables
• Writing good prompts
• Variables API reference