# Shared variables API

18 operations under /api/v1. Errors are RFC 9457 problem+json with a stable `code` field. The complete schemas are in https://nebulactrl.com/api/v1/openapi.json.

## 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.

Authentication: session cookie or `Authorization: Bearer nct_…` token.

Parameters:
- `environmentId` (path, string, required)

Response 200: OK (SharedVariableList)
  - `items` (SharedVariableView[] | null, required)
  - `restaged` (RestagedServiceRef[] | null, required)
  - `warnings` (VariableWarning[] | null, required)
Errors: 401 Unauthorized; 403 Forbidden; 404 Not Found; 422 Unprocessable Entity; 500 Internal Server Error

## PUT /environments/{environmentId}/shared-variables

Upsert environment shared variables (restages consumers)

Authentication: session cookie or `Authorization: Bearer nct_…` token.

Parameters:
- `environmentId` (path, string, required)

Request body (application/json, required): SharedVariablesPutBody
  - `variables` (SharedVariableInput[] | null, required)

Response 200: OK (SharedVariableList)
  - `items` (SharedVariableView[] | null, required)
  - `restaged` (RestagedServiceRef[] | null, required)
  - `warnings` (VariableWarning[] | null, required)
Errors: 401 Unauthorized; 403 Forbidden; 404 Not Found; 422 Unprocessable Entity; 500 Internal Server Error

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

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

Authentication: session cookie or `Authorization: Bearer nct_…` token.

Parameters:
- `environmentId` (path, string, required)
- `key` (path, string, required)

Response 200: OK (SharedVariableList)
  - `items` (SharedVariableView[] | null, required)
  - `restaged` (RestagedServiceRef[] | null, required)
  - `warnings` (VariableWarning[] | null, required)
Errors: 401 Unauthorized; 403 Forbidden; 404 Not Found; 422 Unprocessable Entity; 500 Internal Server Error

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

Version history of an environment shared variable

Authentication: session cookie or `Authorization: Bearer nct_…` token.

Parameters:
- `environmentId` (path, string, required)
- `key` (path, string, required)

Response 200: OK (HistoryOutputBody)
  - `items` (VariableHistoryEntry[] | null, required)
Errors: 401 Unauthorized; 403 Forbidden; 404 Not Found; 422 Unprocessable Entity; 500 Internal Server Error

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

Rotate a generated environment shared variable (plan or stage)

Authentication: session cookie or `Authorization: Bearer nct_…` token.

Parameters:
- `environmentId` (path, string, required)
- `key` (path, string, required)

Request body (application/json, required): VariableRotateBody
  - `dryRun` (boolean, required): true returns the plan and changes nothing; false stages the new value (nothing is deployed)

Response 200: OK (VariableRotationPlan)
  - `affected` (RotationAffected[] | null, required)
  - `blockers` (RotationBlocker[] | null, required)
  - `deployOrder` (string[] | null, required): Service slugs, providers first
  - `key` (string, required)
  - `kind` (enum: app-secret | engine-bound, required)
  - `staged` (boolean, required)
  - `warnings` (string[] | null, required)
Errors: 401 Unauthorized; 403 Forbidden; 404 Not Found; 422 Unprocessable Entity; 500 Internal Server Error

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

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

Authentication: session cookie or `Authorization: Bearer nct_…` token.

Parameters:
- `environmentId` (path, string, required)
- `key` (path, string, required)

Request body (application/json, required): ShareSharedInput
  - `serviceIds` (string[] | null, required)

Response 200: OK (SharedVariableList)
  - `items` (SharedVariableView[] | null, required)
  - `restaged` (RestagedServiceRef[] | null, required)
  - `warnings` (VariableWarning[] | null, required)
Errors: 401 Unauthorized; 403 Forbidden; 404 Not Found; 422 Unprocessable Entity; 500 Internal Server Error

## 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.

Authentication: session cookie or `Authorization: Bearer nct_…` token.

Parameters:
- `projectId` (path, string, required)

Response 200: OK (SharedVariableList)
  - `items` (SharedVariableView[] | null, required)
  - `restaged` (RestagedServiceRef[] | null, required)
  - `warnings` (VariableWarning[] | null, required)
Errors: 401 Unauthorized; 403 Forbidden; 404 Not Found; 422 Unprocessable Entity; 500 Internal Server Error

## PUT /projects/{projectId}/shared-variables

Upsert project shared variables (restages consumers in every environment)

Authentication: session cookie or `Authorization: Bearer nct_…` token.

Parameters:
- `projectId` (path, string, required)

Request body (application/json, required): SharedVariablesPutBody
  - `variables` (SharedVariableInput[] | null, required)

Response 200: OK (SharedVariableList)
  - `items` (SharedVariableView[] | null, required)
  - `restaged` (RestagedServiceRef[] | null, required)
  - `warnings` (VariableWarning[] | null, required)
Errors: 401 Unauthorized; 403 Forbidden; 404 Not Found; 422 Unprocessable Entity; 500 Internal Server Error

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

Delete a project shared variable

Authentication: session cookie or `Authorization: Bearer nct_…` token.

Parameters:
- `projectId` (path, string, required)
- `key` (path, string, required)

Response 200: OK (SharedVariableList)
  - `items` (SharedVariableView[] | null, required)
  - `restaged` (RestagedServiceRef[] | null, required)
  - `warnings` (VariableWarning[] | null, required)
Errors: 401 Unauthorized; 403 Forbidden; 404 Not Found; 422 Unprocessable Entity; 500 Internal Server Error

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

Version history of a project shared variable

Authentication: session cookie or `Authorization: Bearer nct_…` token.

Parameters:
- `projectId` (path, string, required)
- `key` (path, string, required)

Response 200: OK (HistoryOutputBody)
  - `items` (VariableHistoryEntry[] | null, required)
Errors: 401 Unauthorized; 403 Forbidden; 404 Not Found; 422 Unprocessable Entity; 500 Internal Server Error

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

Rotate a generated project shared variable (plan or stage)

Authentication: session cookie or `Authorization: Bearer nct_…` token.

Parameters:
- `projectId` (path, string, required)
- `key` (path, string, required)

Request body (application/json, required): VariableRotateBody
  - `dryRun` (boolean, required): true returns the plan and changes nothing; false stages the new value (nothing is deployed)

Response 200: OK (VariableRotationPlan)
  - `affected` (RotationAffected[] | null, required)
  - `blockers` (RotationBlocker[] | null, required)
  - `deployOrder` (string[] | null, required): Service slugs, providers first
  - `key` (string, required)
  - `kind` (enum: app-secret | engine-bound, required)
  - `staged` (boolean, required)
  - `warnings` (string[] | null, required)
Errors: 401 Unauthorized; 403 Forbidden; 404 Not Found; 422 Unprocessable Entity; 500 Internal Server Error

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

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

Authentication: session cookie or `Authorization: Bearer nct_…` token.

Parameters:
- `projectId` (path, string, required)
- `key` (path, string, required)

Request body (application/json, required): ShareSharedInput
  - `serviceIds` (string[] | null, required)

Response 200: OK (SharedVariableList)
  - `items` (SharedVariableView[] | null, required)
  - `restaged` (RestagedServiceRef[] | null, required)
  - `warnings` (VariableWarning[] | null, required)
Errors: 401 Unauthorized; 403 Forbidden; 404 Not Found; 422 Unprocessable Entity; 500 Internal Server Error

## 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.

Authentication: session cookie or `Authorization: Bearer nct_…` token.

Response 200: OK (SharedVariableList)
  - `items` (SharedVariableView[] | null, required)
  - `restaged` (RestagedServiceRef[] | null, required)
  - `warnings` (VariableWarning[] | null, required)
Errors: 401 Unauthorized; 403 Forbidden; 404 Not Found; 500 Internal Server Error

## PUT /team/shared-variables

Upsert team shared variables (restages consumers in every project)

Authentication: session cookie or `Authorization: Bearer nct_…` token.

Request body (application/json, required): SharedVariablesPutBody
  - `variables` (SharedVariableInput[] | null, required)

Response 200: OK (SharedVariableList)
  - `items` (SharedVariableView[] | null, required)
  - `restaged` (RestagedServiceRef[] | null, required)
  - `warnings` (VariableWarning[] | null, required)
Errors: 401 Unauthorized; 403 Forbidden; 404 Not Found; 422 Unprocessable Entity; 500 Internal Server Error

## DELETE /team/shared-variables/{key}

Delete a team shared variable

Authentication: session cookie or `Authorization: Bearer nct_…` token.

Parameters:
- `key` (path, string, required)

Response 200: OK (SharedVariableList)
  - `items` (SharedVariableView[] | null, required)
  - `restaged` (RestagedServiceRef[] | null, required)
  - `warnings` (VariableWarning[] | null, required)
Errors: 401 Unauthorized; 403 Forbidden; 404 Not Found; 422 Unprocessable Entity; 500 Internal Server Error

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

Version history of a team shared variable

Authentication: session cookie or `Authorization: Bearer nct_…` token.

Parameters:
- `key` (path, string, required)

Response 200: OK (HistoryOutputBody)
  - `items` (VariableHistoryEntry[] | null, required)
Errors: 401 Unauthorized; 403 Forbidden; 404 Not Found; 422 Unprocessable Entity; 500 Internal Server Error

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

Rotate a generated team shared variable (plan or stage)

Authentication: session cookie or `Authorization: Bearer nct_…` token.

Parameters:
- `key` (path, string, required)

Request body (application/json, required): VariableRotateBody
  - `dryRun` (boolean, required): true returns the plan and changes nothing; false stages the new value (nothing is deployed)

Response 200: OK (VariableRotationPlan)
  - `affected` (RotationAffected[] | null, required)
  - `blockers` (RotationBlocker[] | null, required)
  - `deployOrder` (string[] | null, required): Service slugs, providers first
  - `key` (string, required)
  - `kind` (enum: app-secret | engine-bound, required)
  - `staged` (boolean, required)
  - `warnings` (string[] | null, required)
Errors: 401 Unauthorized; 403 Forbidden; 404 Not Found; 422 Unprocessable Entity; 500 Internal Server Error

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

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

Authentication: session cookie or `Authorization: Bearer nct_…` token.

Parameters:
- `key` (path, string, required)

Request body (application/json, required): ShareSharedInput
  - `serviceIds` (string[] | null, required)

Response 200: OK (SharedVariableList)
  - `items` (SharedVariableView[] | null, required)
  - `restaged` (RestagedServiceRef[] | null, required)
  - `warnings` (VariableWarning[] | null, required)
Errors: 401 Unauthorized; 403 Forbidden; 404 Not Found; 422 Unprocessable Entity; 500 Internal Server Error