Install Self-Hosted
Get Started on Cloud
BasicsPipelinesActions & ServicesEnvironmentsIntegrationsTargetsTestsDomainsSandboxesAgents & Tunnels

Create

View as Markdown
  • POST
  • /workspaces
  • /:workspace
  • /variables

Add a new environment variable

Request

REQUIRED SCOPES
VARIABLE_ADD
URL PARAMETERS
workspacerequiredstring
The human-readable ID of the workspace

Example: "my-company"

POST PARAMETERS
typerequiredstring enum
The type of the added variable
Allowed enum:
VAR,
FILE,
SSH_KEY,
IOS_KEYCHAIN,
IOS_PROVISION_PROFILES,
SSH_PUBLIC_KEY,
GPG_KEY
urlread-onlystring
API endpoint to GET this object
html_urlread-onlystring
Web URL to view this object in Buddy.works
keyrequiredstring
The name of the variable
valuestring
The value of the variable
settableboolean
If set to true the variable value can be set by Buddy actions
run_only_settableboolean
Available only if type=VAR. If set to true the variable value can be set by Buddy actions only for execution time
encryptedboolean
If set to true the variable value will be encrypted and hidden
descriptionstring
The optional description of the variable
init_pathstring
Initial path for the variable
defaultsstring
Default value for the variable
file_pathstring
Specifies where to copy the file on each run. Set if type is SSH_KEY
file_chmodstring
File permission set on copy to a container on each run. Set if type is SSH_KEY
file_placestring enum
Set if type is SSH_KEY. If it's NONE, the variable can be used as a parameter in an action. For CONTAINER, the given key is additionally copied to an action container on each run
Allowed enum:
NONE,
CONTAINER
passwordstring
Password for certificates
passphrasestring
Passphrase for encrypted SSH keys
key_identifierstring
GPG key identifier
projectProjectNameView
Project reference (by name)
pipelinePipelineIdView
Pipeline reference
actionActionIdView
Action reference
sandboxSandboxIdView
Sandbox reference
environmentEnvironmentIdView
Environment reference

Response

RESPONSE BODY
typestring enum
The type of the added variable
Allowed enum:
VAR,
FILE,
SSH_KEY,
IOS_KEYCHAIN,
IOS_PROVISION_PROFILES,
SSH_PUBLIC_KEY,
GPG_KEY
urlread-onlystring
API endpoint to GET this object
html_urlread-onlystring
Web URL to view this object in Buddy.works
idinteger
The ID of the variable
keyrequiredstring
The name of the variable
valuestring
The value of the variable
encryptedboolean
If set to true the variable value will be encrypted and hidden
descriptionstring
The optional description of the variable
settableboolean
If set to true the variable value can be set by Buddy actions
projectProjectView
pipelineShortPipelineView
Short representation of a pipeline
actionActionIdView
Action reference
sandboxSandboxIdView
Sandbox reference
environmentEnvironmentIdView
Environment reference
run_only_settableboolean
Available only if type=VAR. If set to true the variable value can be set by Buddy actions only for execution time
init_pathstring
Initial path for the variable
defaultsstring
Default value for the variable
file_pathstring
Specifies where to copy the file on each run. Set if type is SSH_KEY
file_chmodstring
File permission set on copy to a container on each run. Set if type is SSH_KEY
file_placestring enum
Set if type is SSH_KEY. If it's NONE, the variable can be used as a parameter in an action. For CONTAINER, the given key is additionally copied to an action container on each run
Allowed enum:
NONE,
CONTAINER
binaryboolean
Whether the file is binary
public_valuestring
Public value for SSH key type variables
key_fingerprintstring
Fingerprint of SSH key
checksumstring
Checksum of the variable value
passwordstring
Password for certificates
passphrasestring
Passphrase for encrypted SSH keys
key_identifierstring
GPG key identifier

Last modified on Jan 26, 2026

Previous pageListNext pageGet

Examples

Project-scoped variablePipeline-scoped variableAction-scoped variableSandbox-scoped variableWorkspace-scoped SSH key

Example: Project-scoped variable

curl -X POST "https://api.buddy.works/workspaces/:workspace/variables" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "key": "my_var",
  "value": "some value",
  "project": {
    "name": "my-project"
  },
  "type": "VAR",
  "settable": true,
  "run_only_settable": true
}'

Example: Pipeline-scoped variable

curl -X POST "https://api.buddy.works/workspaces/:workspace/variables" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "key": "my_var",
  "value": "some value",
  "pipeline": {
    "id": 1
  }
}'

Example: Action-scoped variable

curl -X POST "https://api.buddy.works/workspaces/:workspace/variables" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "key": "my_var",
  "value": "some value",
  "action": {
    "id": 1
  }
}'

Example: Sandbox-scoped variable

curl -X POST "https://api.buddy.works/workspaces/:workspace/variables" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "key": "my_var",
  "value": "some value",
  "sandbox": {
    "id": "u3ep173pzbjez"
  }
}'

Example: Workspace-scoped SSH key

curl -X POST "https://api.buddy.works/workspaces/:workspace/variables" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "value": "-----BEGIN RSA PRIVATE KEY-----\nMIIEpAIBAAKCAQEA...\n-----END RSA PRIVATE KEY-----",
  "type": "SSH_KEY",
  "key": "id_my_key",
  "encrypted": true,
  "description": "My Server Key",
  "file_path": "~/.ssh/id_my_key",
  "file_chmod": "600",
  "file_place": "CONTAINER"
}'
EXAMPLE RESPONSE
{
  "url": "https://api.buddy.works/workspaces/my-company/variables/123",
  "html_url": "https://buddy.works/my-company/-/environment-variables/edit/123",
  "id": 123,
  "key": "id_workspace",
  "type": "SSH_KEY",
  "encrypted": true,
  "description": "",
  "settable": false,
  "value": "!encrypted SmFXMKglBP8n/3JKGFtjpbOj1RPpHHkGNa+/uoGbeEJXA/D9nALanxozDtshHD8kPjpgfJC8VgXhpC10akKcPnOwOLhpnm0FVK7EQRxaTYd+ZhhiqqINJQXeAQccq52pNtpLVC10qOyWUrYbbD5JguwaIrDI3AnVx/pxOaaSjOVama+6wU6gg0H/2BdOwaiqpGvAkofIMbiROIZkRnO48gU+FEl/+Wkq0nHg0yVdRjX61GWZGNL1tfB+cVBuNLg149yhLJUQY+JVXlGO/562qMYnEk0NMVohauGjRT/4RdJeCx39lOR0VsabMsl9hVU23EXjmcjVzL+fP+PLmjst8bFNRwL+dz2xOhMddIe2YJ4zYp3GXClnMP7DlQn/xyFFFqFS+UQ+AylnCHYTA68cfIqnbAJ23Yout+cRKPUrf2J20iGKdwUANojfabtjyRzjynBcDXALExCmBEOQ63FmKktvOTDx3onH9c37CwRlgoxgePCz4GJHFBqKxaY+LRVcB6q/zsYggdVr785IJnbRfg==.sV8Jqv5sfFL1VJ2lQCwoVg==",
  "file_path": "~/.ssh/id_toprus",
  "file_chmod": "600",
  "file_place": "CONTAINER",
  "public_value": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIMgI3BdloRSGhzUgdA8FMZjI+sYvRTkTw92lwiFMntUw toprus Key",
  "key_fingerprint": "59:4e:4a:72:ff:4c:15:36:82:83:11:77:a5:b6:b6:b9",
  "checksum": "a3114c53b8328869b4f6020559618d56f9522e76763532abfc3a585aaea1f51d"
}
STATUS
201 Created