API reference

Environment variables

Read and change a project's environment variables.

Values are encrypted at rest; sensitive values are never returned. See Environment variables for targets and the names the platform reserves.

`GET /v1/orgs/:orgId/projects/:projectId/env`

Lists the project's variables. Values of sensitive variables are null.

Auth: user access token or platform agent key · Scope: env:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:projectId`	Project id (`prj_…`).

Response 200

{
  vars: {
    value: null | string
    createdAt?: number
    updatedAt?: number
    orgId: string
    projectId: string
    key: string
    targets: ("preview" | "production" | "development")[]
    sensitive?: boolean
    updatedBy: string
  }[]
}

`POST /v1/orgs/:orgId/projects/:projectId/env`

Creates or replaces many variables at once (e.g. a pasted .env file), all with the same environments and sensitivity. Nothing is written unless every key is valid.

Auth: user access token or platform agent key · Scope: env:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:projectId`	Project id (`prj_…`).

Request body

Field	Type	Required	Default	Notes
`vars`	`object[]`	Yes		1–200 items
`vars[].key`	`string`	Yes		1–256 characters
`vars[].value`	`string`	Yes		up to 65,536 characters
`targets`	`("production" \| "preview" \| "development")[]`	Yes		at least 1 item
`sensitive`	`boolean`	No	`true`

Response 200

{
  keys: string[]
  targets: ("preview" | "production" | "development")[]
  sensitive: boolean
}

Errors

Status	Message
`400`	Invalid names: …. Use letters, numbers and underscores, not starting with a number.
`400`	Reserved by the platform: ….
`404`	Project not found
`503`	Some variables weren't saved. Try again.

`PUT /v1/orgs/:orgId/projects/:projectId/env/:key`

Creates or replaces a variable. Omit value to keep the stored value, for example to change the targets of a sensitive variable.

Auth: user access token or platform agent key · Scope: env:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:projectId`	Project id (`prj_…`).
`:key`	Variable name.

Request body

Field	Type	Required	Default	Notes
`value`	`string`	No		up to 65,536 characters
`targets`	`("production" \| "preview" \| "development")[]`	Yes		at least 1 item
`sensitive`	`boolean`	No	`true`

Response 200

{
  key: string
  targets: ("preview" | "production" | "development")[]
  sensitive: boolean
}

Errors

Status	Message
`400`	Use letters, numbers and underscores, not starting with a number.
`400`	… is reserved by the platform.
`400`	Enter a value.
`400`	Enter a new value to make this variable visible.
`404`	Project not found

`DELETE /v1/orgs/:orgId/projects/:projectId/env/:key`

Deletes a variable. Running deployments keep the value they started with.

Auth: user access token or platform agent key · Scope: env:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:projectId`	Project id (`prj_…`).
`:key`	Variable name.

Response 204 with no body.