Skip to main content
The Project Variables API provides two sets of endpoints for managing project variables and environment-level overrides for each project variable.

​
Get project variables

This endpoint allows you to list project variables for a given account and project. As a pageable endpoint within , results are paged through by appending the page information as query parameters in the request URL. The paging parameters are as follows:
ParameterPurposeDefault valueExample value
pageWhich page to fetch02
sizeHow large each page of results should be2510
These would be appended to the URL as query parameters, for example: Paged request URL: GET /v1/projects/{projectId}/variables?page=2&size=10 If no paging information is provided, the defaults listed above will be used instead.

​
Example request

Base URL: GET /v1/projects/{projectId}/variables Example success response: 
HTTP 200 OK
{
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "test-variable-1",
      "type": "TEXT",
      "behaviour": "SHARED",
      "description": "A test text variable",
      "value": "test-value-1",
      "supportsDoubleResolution": false
    },
    {
      "id": "7d350099-17c1-42d6-9035-0bd92c68ebb0",
      "name": "test-variable-2",
      "type": "NUMBER",
      "behaviour": "COPIED",
      "description": "A test number variable",
      "value": 42,
      "supportsDoubleResolution": true
    }
  ],
  "page": 0,
  "size": 2,
  "total": 2
}

​
Create project variable

This endpoint allows you to create a new project variable for a given account and project.

​
Example request

Base URL: POST /v1/projects/{projectId}/variables Example request body: 
{
  "name": "test_create_variable",
  "type": "TEXT",
  "behaviour": "SHARED",
  "description": "A new test variable created via API",
  "value": "variable-value",
  "supportsDoubleResolution": false
}
Example success response: 
HTTP 201 Created
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "test_create_variable",
  "value": "variable-value"
}

​
Update project variable

This endpoint allows you to perform a partial update to an existing project variable, identified by the immutable variable name. Currently, type and behaviour are required parameters of the request, even if the values are to remain unchanged.

​
Example request

Base URL: PATCH /v1/projects/{projectId}/variables/{variableName} Example request body: 
{
  "type": "TEXT",
  "behaviour": "SHARED",
  "description": "An updated description of a test variable created via API",
  "value": "variable-value-updated",
  "supportsDoubleResolution": false
}
Example success response: 
HTTP 204 No Content

{}

​
Delete project variable

This endpoint allows you to delete a variable by name, along with all environment-level overrides for the variable.

​
Example request

Base URL: DELETE /v1/projects/{projectId}/variables/{variableName} Example success response: 
HTTP 204 No Content

{}

​
Get project variable environment overrides

This endpoint allows you to retrieve a variable along with any associated environment-level overrides. You can choose to provide an environment name to return a single override.

​
Example request without a specified environment

Base URL: GET /v1/projects/{projectId}/variables/{variableName}/environment-overrides Example success response: 
HTTP 200 OK
{
  "variable": {
    "id": "12345678-1234-1234-1234-123456789012",
    "name": "test_variable",
    "type": "TEXT"
  },
  "overrides": [
    {
      "environmentName": "dev",
      "value": "dev-override-value"
    },
    {
      "environmentName": "staging",
      "value": "staging-override-value"
    },
    {
      "environmentName": "prod",
      "value": "prod-override-value"
    }
  ]
}

​
Example request with a specified environment

Base URL: GET /v1/projects/{projectId}/variables/{variableName}/environment-overrides?environmentName=dev Example success response: 
HTTP 200 OK
{
  "variable": {
    "id": "12345678-1234-1234-1234-123456789012",
    "name": "test_variable",
    "type": "TEXT"
  },
  "overrides": [
    {
      "environmentName": "dev",
      "value": "dev-override-value"
    }
  ]
}

​
Create project variable environment overrides

This endpoint allows you to create new environment-level overrides for an existing project variable, or to update existing overrides. If you specify an environment that doesn’t already have an override for the specified project variable, this will create a new environment-level override for that project variable. If you specify an environment that does already have an override for the specified project variable, the override will be updated. If any environment overrides are unable to be created, an entry will be included in the failedOverride portion of the response. Common error scenarios include:
  • The environment does not exist.
  • You don’t have permission to create or edit environment overrides.
  • The provided value for the override doesn’t have a compatible type for the variable (for example, providing a number as an override for a text variable).

​
Example request

Base URL: POST /v1/projects/{projectId}/variables/{variableName}/environment-overrides Example request: 
{
  "overrides": [
    {
      "environmentName": "dev",
      "value": "dev-override-value"
    },
    {
      "environmentName": "prod",
      "value": "prod-override-value"
    }
  ]
}
Example success response: 
HTTP 200 OK
{
  "variableName": "test_variable",
  "type": "TEXT",
  "successfulOverrides": [
    {
      "environmentName": "dev",
      "value": "dev-override-value"
    },
    {
      "environmentName": "prod",
      "value": "prod-override-value"
    }
  ],
  "failedOverrides": []
}

​
Delete project variable environment override

This endpoint allows you to remove a specific environment-level override from an existing project variable, specified by environment name.

​
Example request

Base URL: DELETE /v1/projects/{projectId}/variables/{variableName}/environment-overrides/{environmentName} Example success response: 
HTTP 204 No Content

{}