Skip to content
NebulaCtrlInstall

Reference

View as Markdown

Shared variables API

18 operations. Every call needs a session cookie or an Authorization: Bearer nct_… token unless marked Public. Conventions, errors and scopes

GET/environments/{environmentId}/shared-variables

List an environment's shared variables (own values plus inherited project values)

Shared variables reach a service only through an explicit KEY=${{shared.KEY}} variable (see share). An environment value overrides the project value for that environment. Shared values may only reference other shared variables, team variables, external secrets, generators and transforms.

ParameterInTypeDescription
environmentIdrequiredpathstring
Response 200 · OK · application/json
SharedVariableList
  • SharedVariableView[] | nullrequired
  • RestagedServiceRef[] | nullrequired
  • VariableWarning[] | nullrequired
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

PUT/environments/{environmentId}/shared-variables

Upsert environment shared variables (restages consumers)

ParameterInTypeDescription
environmentIdrequiredpathstring
Request body · application/json · required
SharedVariablesPutBody
  • SharedVariableInput[] | nullrequired
Response 200 · OK · application/json
SharedVariableList
  • SharedVariableView[] | nullrequired
  • RestagedServiceRef[] | nullrequired
  • VariableWarning[] | nullrequired
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

DELETE/environments/{environmentId}/shared-variables/{key}

Delete an environment shared variable (falls back to the project value)

ParameterInTypeDescription
environmentIdrequiredpathstring
keyrequiredpathstring
Response 200 · OK · application/json
SharedVariableList
  • SharedVariableView[] | nullrequired
  • RestagedServiceRef[] | nullrequired
  • VariableWarning[] | nullrequired
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

GET/environments/{environmentId}/shared-variables/{key}/history

Version history of an environment shared variable

ParameterInTypeDescription
environmentIdrequiredpathstring
keyrequiredpathstring
Response 200 · OK · application/json
HistoryOutputBody
  • VariableHistoryEntry[] | nullrequired
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

POST/environments/{environmentId}/shared-variables/{key}/rotate

Rotate a generated environment shared variable (plan or stage)

ParameterInTypeDescription
environmentIdrequiredpathstring
keyrequiredpathstring
Request body · application/json · required
VariableRotateBody
  • dryRunbooleanrequired
    true returns the plan and changes nothing; false stages the new value (nothing is deployed)
Response 200 · OK · application/json
VariableRotationPlan
  • RotationAffected[] | nullrequired
  • RotationBlocker[] | nullrequired
  • deployOrderstring[] | nullrequired
    Service slugs, providers first
  • keystringrequired
  • kindenum: app-secret | engine-boundrequired
  • stagedbooleanrequired
  • warningsstring[] | nullrequired
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

POST/environments/{environmentId}/shared-variables/{key}/share

Stage KEY=${{shared.KEY}} on services

ParameterInTypeDescription
environmentIdrequiredpathstring
keyrequiredpathstring
Request body · application/json · required
ShareSharedInput
  • serviceIdsstring[] | nullrequired
Response 200 · OK · application/json
SharedVariableList
  • SharedVariableView[] | nullrequired
  • RestagedServiceRef[] | nullrequired
  • VariableWarning[] | nullrequired
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

GET/projects/{projectId}/shared-variables

List a project's shared variables

Shared variables reach a service only through an explicit KEY=${{shared.KEY}} variable (see share). An environment value overrides the project value for that environment. Shared values may only reference other shared variables, team variables, external secrets, generators and transforms.

ParameterInTypeDescription
projectIdrequiredpathstring
Response 200 · OK · application/json
SharedVariableList
  • SharedVariableView[] | nullrequired
  • RestagedServiceRef[] | nullrequired
  • VariableWarning[] | nullrequired
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

PUT/projects/{projectId}/shared-variables

Upsert project shared variables (restages consumers in every environment)

ParameterInTypeDescription
projectIdrequiredpathstring
Request body · application/json · required
SharedVariablesPutBody
  • SharedVariableInput[] | nullrequired
Response 200 · OK · application/json
SharedVariableList
  • SharedVariableView[] | nullrequired
  • RestagedServiceRef[] | nullrequired
  • VariableWarning[] | nullrequired
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

DELETE/projects/{projectId}/shared-variables/{key}

Delete a project shared variable

ParameterInTypeDescription
projectIdrequiredpathstring
keyrequiredpathstring
Response 200 · OK · application/json
SharedVariableList
  • SharedVariableView[] | nullrequired
  • RestagedServiceRef[] | nullrequired
  • VariableWarning[] | nullrequired
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

GET/projects/{projectId}/shared-variables/{key}/history

Version history of a project shared variable

ParameterInTypeDescription
projectIdrequiredpathstring
keyrequiredpathstring
Response 200 · OK · application/json
HistoryOutputBody
  • VariableHistoryEntry[] | nullrequired
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

POST/projects/{projectId}/shared-variables/{key}/rotate

Rotate a generated project shared variable (plan or stage)

ParameterInTypeDescription
projectIdrequiredpathstring
keyrequiredpathstring
Request body · application/json · required
VariableRotateBody
  • dryRunbooleanrequired
    true returns the plan and changes nothing; false stages the new value (nothing is deployed)
Response 200 · OK · application/json
VariableRotationPlan
  • RotationAffected[] | nullrequired
  • RotationBlocker[] | nullrequired
  • deployOrderstring[] | nullrequired
    Service slugs, providers first
  • keystringrequired
  • kindenum: app-secret | engine-boundrequired
  • stagedbooleanrequired
  • warningsstring[] | nullrequired
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

POST/projects/{projectId}/shared-variables/{key}/share

Stage KEY=${{shared.KEY}} on services

ParameterInTypeDescription
projectIdrequiredpathstring
keyrequiredpathstring
Request body · application/json · required
ShareSharedInput
  • serviceIdsstring[] | nullrequired
Response 200 · OK · application/json
SharedVariableList
  • SharedVariableView[] | nullrequired
  • RestagedServiceRef[] | nullrequired
  • VariableWarning[] | nullrequired
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

GET/team/shared-variables

List the team's shared variables

Team variables apply to every project of the team and are referenced as ${{team.KEY}}. Like shared variables they reach a service only through an explicit KEY=${{team.KEY}} variable (see share). Only owners and admins may change them; a principal restricted to some projects has no access. Team values may only reference other team variables, external secrets (${{vault:integration/path#key}}), generators and transforms.

Response 200 · OK · application/json
SharedVariableList
  • SharedVariableView[] | nullrequired
  • RestagedServiceRef[] | nullrequired
  • VariableWarning[] | nullrequired
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

PUT/team/shared-variables

Upsert team shared variables (restages consumers in every project)

Request body · application/json · required
SharedVariablesPutBody
  • SharedVariableInput[] | nullrequired
Response 200 · OK · application/json
SharedVariableList
  • SharedVariableView[] | nullrequired
  • RestagedServiceRef[] | nullrequired
  • VariableWarning[] | nullrequired
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

DELETE/team/shared-variables/{key}

Delete a team shared variable

ParameterInTypeDescription
keyrequiredpathstring
Response 200 · OK · application/json
SharedVariableList
  • SharedVariableView[] | nullrequired
  • RestagedServiceRef[] | nullrequired
  • VariableWarning[] | nullrequired
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

GET/team/shared-variables/{key}/history

Version history of a team shared variable

ParameterInTypeDescription
keyrequiredpathstring
Response 200 · OK · application/json
HistoryOutputBody
  • VariableHistoryEntry[] | nullrequired
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

POST/team/shared-variables/{key}/rotate

Rotate a generated team shared variable (plan or stage)

ParameterInTypeDescription
keyrequiredpathstring
Request body · application/json · required
VariableRotateBody
  • dryRunbooleanrequired
    true returns the plan and changes nothing; false stages the new value (nothing is deployed)
Response 200 · OK · application/json
VariableRotationPlan
  • RotationAffected[] | nullrequired
  • RotationBlocker[] | nullrequired
  • deployOrderstring[] | nullrequired
    Service slugs, providers first
  • keystringrequired
  • kindenum: app-secret | engine-boundrequired
  • stagedbooleanrequired
  • warningsstring[] | nullrequired
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

POST/team/shared-variables/{key}/share

Stage KEY=${{team.KEY}} on services

ParameterInTypeDescription
keyrequiredpathstring
Request body · application/json · required
ShareSharedInput
  • serviceIdsstring[] | nullrequired
Response 200 · OK · application/json
SharedVariableList
  • SharedVariableView[] | nullrequired
  • RestagedServiceRef[] | nullrequired
  • VariableWarning[] | nullrequired
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.