Variables

Variables store non-sensitive configuration values — URLs, feature flags, settings. Unlike secrets, values are stored in plaintext and returned in read responses. There is no usage limit.

Like secrets, a variable can be scoped to an environment (default, development, staging, production). The default environment applies everywhere; the same name can exist once per environment.

List Variables

Returns all variables in the project, values included.

GET /v1/projects/:projectId/variables

Query Parameters

Parameter	Type	Required	Description
`environment`	`string`	No	Only return variables scoped to this environment. One of `default`, `development`, `staging`, `production`.

Response

{
  "success": true,
  "data": [
    {
      "id": "clx...",
      "name": "API_URL",
      "description": "Public API base URL",
      "value": "https://api.example.com",
      "environment": "production",
      "createdBy": "user_...",
      "updatedBy": "user_...",
      "createdAt": "2025-01-15T10:30:00.000Z",
      "updatedAt": "2025-01-16T08:00:00.000Z",
      "createdByUser": { "id": "user_...", "name": "Jane", "email": "[email protected]" },
      "updatedByUser": { "id": "user_...", "name": "Jane", "email": "[email protected]" }
    }
  ]
}

Get Variable

GET /v1/projects/:projectId/variables/:variableId

Returns a single variable, value included.

Create Variable

Requires variables:write scope and owner/admin role.

POST /v1/projects/:projectId/variables

Request Body

Field	Type	Required	Description
`name`	`string`	Yes	Uppercase letters, numbers, underscores. Must start with a letter.
`value`	`string`	Yes	The variable value (1–10,000 characters).
`description`	`string`	No	Optional description (max 500 characters).
`environment`	`string`	No	Environment to scope the variable to: `default`, `development`, `staging`, or `production`. Defaults to `default`, which applies everywhere.

Response `201`

Returns the created variable (same shape as the list response).

Error `409`

Returned when a variable with the same name already exists in the same environment. The same name can be reused across different environments.

Update Variable

Requires variables:write scope and owner/admin role.

PATCH /v1/projects/:projectId/variables/:variableId

Request Body

Field	Type	Required	Description
`value`	`string`	No	The new value.
`description`	`string`	No	Updated description.

At least one field must be provided.

Response

Returns the updated variable.

Delete Variable

Requires variables:write scope and owner/admin role.

DELETE /v1/projects/:projectId/variables/:variableId

Returns 204 No Content on success.

Using Variables in Apps

Project variables can be linked directly to app environment variables, the same way secrets are. Instead of retyping the same URL or feature flag into every app, reference a variable — its current value is resolved at deploy time.

In the app settings or creation wizard, click Link variable in the environment variables section and select one or more variables from the picker. Each linked variable appears as an env var with the variable's name as the key, shown as "Linked to variable" instead of an editable value.

When the app deploys or redeploys, linked env vars are resolved to their current values. Because variables are non-sensitive, they are injected as plain env vars (not marked secret). If you update a variable, the new value takes effect on the next redeploy.

Linked env vars include projectVariableId in the API payload:

{
  "envVars": [
    { "key": "API_URL", "value": "", "projectVariableId": "clx..." }
  ]
}

On this page