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

# API Reference & Migration

> Variable schemas, file locations, and migration from legacy

## Variable Schema

```typescript theme={null}
interface Variable {
  id: string;
  name: string;                  // snake_case
  description?: string;
  dataType: DataType;            // 'string' | 'number' | 'boolean' | 'array' | 'object'
  enumValues?: EnumValue[];
  isEnumEnabled?: boolean;
  isRequired?: boolean;
  defaultValue?: any;
  extractionPrompt?: string;
  sourceNodeId?: string;
  sourceNodeType?: string;
  properties?: Variable[];       // object
  item?: Variable;               // array
}
```

## Static Variable Schema

```typescript theme={null}
interface StaticVariable {
  id: string;
  name: string;
  description?: string;
  dataType: DataType;
  value: any;                    // may include {{variable_name}}
}
```

## Data Types

```typescript theme={null}
type DataType = 'string' | 'number' | 'boolean' | 'array' | 'object';
```

## Enum Value Schema

```typescript theme={null}
interface EnumValue {
  value: string;
  label?: string;
}
```

## File Locations

**Stores:**\
`variables.store.ts`, `flow-variables-bridge.ts`, `variable.schemas.ts`, `node.schemas.ts` under `src/features/agents/flow-builder/` (stores, schemas).

**Utils:**\
`variable-context.ts`, `variable-context-rules.ts`, `jsonpath-mapper.ts`, `variable-detection.ts` under `src/features/agents/flow-builder/utils/`.

**Components:**\
Variables panel, variables card, static variables builder, variable text input, variables builder under `src/features/agents/flow-builder/components/`.

**Hooks:**\
`use-variable-context.ts`, `use-variable-categories.ts`, `use-global-variable-validation.ts` under `src/features/agents/flow-builder/hooks/`.

## Migration from Legacy Variable System

1. **System variables:** Map old names to current system variables.
2. **Extracted variables:** Update to new extraction config format.
3. **Custom variables:** Move workflow-level variables into custom variables.
4. **Static variables:** Map node-level constants to static variables.
5. **Validation:** Run validation and fix any errors.
6. **Testing:** Re-test all flows and single-prompt agents.

### Breaking Changes

* Node-specific context variables (e.g. `conversation_history`, `tool_response`) are no longer used.
* Availability is strictly by flow execution order.
* Global nodes cannot use extracted or static variables.
* JSONPath in the UI uses `$.` (still converted to `result.` in the backend).

***

**Last updated:** February 2026 · **Version:** 2.0