Variables API

Complete API reference for managing environment variables with JavaScript, cURL, and MCP examples.

Overview

Variables are secure, environment-scoped key-value pairs injected into workflow execution contexts. Variable values are write-only - they are never returned in API responses for security.

Endpoints

Operation	Method	Endpoint
List	GET	/api/variables?organizationId={id}&environmentId={id}
Create	POST	/api/variables
Get by ID	GET	/api/variables/{id}
Update	PUT	/api/variables/{id}
Delete	DELETE	/api/variables/{id}

---

List Variables

Retrieve variables for an organization, optionally filtered by environment.

cURL

curl -X GET "https://console.rocketwavelabs.io/api/variables?organizationId=ORG_UUID&environmentId=ENV_UUID&page=1&limit=10" \
  -H "Cookie: rocketwave_session=YOUR_SESSION_TOKEN"

JavaScript

// Using the VariableService
import { variableService } from '@/app/services/variableService';

const result = await variableService.getAll(1, 10, 'ORG_UUID', 'ENV_UUID');
console.log(result.data);       // Array of variables
console.log(result.pagination); // { page, limit, total, totalPages }

// Using fetch directly
const response = await fetch('/api/variables?organizationId=ORG_UUID&environmentId=ENV_UUID', {
  credentials: 'include'
});
const data = await response.json();

MCP

const response = await fetch('https://console.rocketwavelabs.io/api/mcp/tools/call', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  credentials: 'include',
  body: JSON.stringify({
    name: 'variables_list',
    arguments: {
      organizationId: 'ORG_UUID',
      environmentId: 'ENV_UUID',
      page: 1,
      limit: 10
    }
  })
});

Response

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "organizationId": "ORG_UUID",
      "environmentId": "ENV_UUID",
      "name": "OPENAI_API_KEY",
      "organization": { "name": "Acme Corp" },
      "environment": { "name": "Production" },
      "createdAt": "2025-01-15T10:00:00Z",
      "updatedAt": "2025-01-15T10:00:00Z"
    }
  ],
  "pagination": { "page": 1, "limit": 10, "total": 5, "totalPages": 1 }
}

Security

The value field is never returned - it's a write-only field for security.

---

Create Variable

Create a new environment variable.

cURL

curl -X POST "https://console.rocketwavelabs.io/api/variables" \
  -H "Content-Type: application/json" \
  -H "Cookie: rocketwave_session=YOUR_SESSION_TOKEN" \
  -d '{
    "organizationId": "ORG_UUID",
    "environmentId": "ENV_UUID",
    "name": "MASTODON_ACCESS_TOKEN",
    "value": "your-secret-access-token"
  }'

JavaScript

// Using the VariableService
import { variableService } from '@/app/services/variableService';

const variable = await variableService.create({
  organizationId: 'ORG_UUID',
  environmentId: 'ENV_UUID',
  name: 'MASTODON_ACCESS_TOKEN',
  value: 'your-secret-access-token'
});

// Using fetch directly
const response = await fetch('/api/variables', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  credentials: 'include',
  body: JSON.stringify({
    organizationId: 'ORG_UUID',
    environmentId: 'ENV_UUID',
    name: 'MASTODON_ACCESS_TOKEN',
    value: 'your-secret-access-token'
  })
});

MCP

const response = await fetch('https://console.rocketwavelabs.io/api/mcp/tools/call', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  credentials: 'include',
  body: JSON.stringify({
    name: 'variables_create',
    arguments: {
      organizationId: 'ORG_UUID',
      environmentId: 'ENV_UUID',
      name: 'MASTODON_ACCESS_TOKEN',
      value: 'your-secret-access-token'
    }
  })
});

Request Body

Field	Type	Required	Description
organizationId	UUID	Yes	Organization ID
environmentId	UUID	Yes	Environment ID
name	string	Yes	Variable name (e.g., OPENAI_API_KEY)
value	string	Yes	Secret value to store

Response (201)

{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "organizationId": "ORG_UUID",
  "environmentId": "ENV_UUID",
  "name": "MASTODON_ACCESS_TOKEN",
  "organization": { "name": "Acme Corp" },
  "environment": { "name": "Production" },
  "createdAt": "2025-01-27T10:00:00Z",
  "updatedAt": "2025-01-27T10:00:00Z"
}

Error Responses

Status	Description
400	Missing required fields
409	Variable with this name already exists in this organization/environment
500	Internal server error

---

Get Variable by ID

Retrieve a single variable by its ID.

cURL

curl -X GET "https://console.rocketwavelabs.io/api/variables/VARIABLE_UUID" \
  -H "Cookie: rocketwave_session=YOUR_SESSION_TOKEN"

JavaScript

const variable = await variableService.getById('VARIABLE_UUID');

MCP

const response = await fetch('https://console.rocketwavelabs.io/api/mcp/tools/call', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  credentials: 'include',
  body: JSON.stringify({
    name: 'variables_get',
    arguments: { id: 'VARIABLE_UUID' }
  })
});

---

Update Variable

Update an existing variable's name and/or value.

cURL

curl -X PUT "https://console.rocketwavelabs.io/api/variables/VARIABLE_UUID" \
  -H "Content-Type: application/json" \
  -H "Cookie: rocketwave_session=YOUR_SESSION_TOKEN" \
  -d '{
    "name": "MASTODON_ACCESS_TOKEN_V2",
    "value": "new-secret-token"
  }'

JavaScript

// Using the VariableService
const updated = await variableService.update('VARIABLE_UUID', {
  name: 'MASTODON_ACCESS_TOKEN_V2',
  value: 'new-secret-token'  // Optional: omit to keep existing value
});

// Using fetch directly
const response = await fetch('/api/variables/VARIABLE_UUID', {
  method: 'PUT',
  headers: { 'Content-Type': 'application/json' },
  credentials: 'include',
  body: JSON.stringify({
    name: 'MASTODON_ACCESS_TOKEN_V2',
    value: 'new-secret-token'
  })
});

MCP

const response = await fetch('https://console.rocketwavelabs.io/api/mcp/tools/call', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  credentials: 'include',
  body: JSON.stringify({
    name: 'variables_update',
    arguments: {
      id: 'VARIABLE_UUID',
      name: 'MASTODON_ACCESS_TOKEN_V2',
      value: 'new-secret-token'
    }
  })
});

Request Body

Field	Type	Required	Description
name	string	Yes	New variable name
value	string	No	New value (omit to keep existing)

---

Delete Variable

Permanently delete a variable.

cURL

curl -X DELETE "https://console.rocketwavelabs.io/api/variables/VARIABLE_UUID" \
  -H "Cookie: rocketwave_session=YOUR_SESSION_TOKEN"

JavaScript

await variableService.delete('VARIABLE_UUID');

MCP

const response = await fetch('https://console.rocketwavelabs.io/api/mcp/tools/call', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  credentials: 'include',
  body: JSON.stringify({
    name: 'variables_delete',
    arguments: { id: 'VARIABLE_UUID' }
  })
});

Response

{
  "success": true
}

---

Using Variables in Workflows

Variables are automatically injected into the V8 execution context during workflow execution.

Direct Access

// Variables are available as top-level variables
const apiKey = OPENAI_API_KEY;
const serverUrl = MASTODON_SERVER_URL;

Variables Array

// Access all variables as an array
for (const variable of __variables__) {
  print(`${variable.name}: defined`);
}

Variables by Name Map

// Access variables by name from a lookup object
const token = __variablesByName__['API_TOKEN'];

Best Practices

Naming Conventions

• Use SCREAMING_SNAKE_CASE for consistency
• Prefix with service name: MASTODON_ACCESS_TOKEN, OPENAI_API_KEY
• Avoid generic names like TOKEN or KEY

Environment Separation

Development Environment:
  - MASTODON_SERVER_URL: https://mastodon.social (test server)
  - DEBUG_MODE: true

Production Environment:
  - MASTODON_SERVER_URL: https://your-instance.com
  - DEBUG_MODE: false

Related Topics

• Settings UI — Variable management interface
• Scripts Reference — Using variables in workflow scripts
• Models API — AI model management