Env Applications

List Environment Variables

GET /v1/applications/{uuid}/env

List an app's environment variables. Each variable is injected into the build with its exact name (so VITE_API_URL or NEXT_PUBLIC_* reaches your bundler as-is) and, for a managed, full-stack, WordPress or function app, into the running app. A secret's value is never returned — is_secret is true and value is empty.

The list also carries the variables a database connection gives the app (source: "database"): {PREFIX}DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD and DATABASE_URL, the last two masked like any secret. ngris builds them from the connection when it starts the app; they are not stored as variables and can't be set or deleted here — disconnect the database instead.

Variable fields

name string

The variable name ([A-Za-z_][A-Za-z0-9_]*).

value string

The value — empty for secrets (write-only).

is_secret bool

Secrets are encrypted at rest and never returned.

environment string

The deploys that get it: production, preview or all. preview means branch previews only; a deploy waiting to be promoted (activate=false) gets the production variables. When a name is set for all and for one environment, that environment's own value wins there.

source string

user: a variable you set. database: given by a database connection (read-only here).

connection_uuid, database_uuid, database_name, database_user_uuid, database_user_name string?

On a database row only (omitted on your own variables): the connection, database and user it comes from.

pending bool?

On a database row only: true while the database or its user isn't ready; the variable reaches the app once both are. Omitted when false.

Response — 200 OK
{
  "env": [
    { "name": "VITE_API_URL", "value": "https://api.example.com", "is_secret": false, "environment": "all", "source": "user" },
    { "name": "SENTRY_TOKEN", "value": "", "is_secret": true, "environment": "production", "source": "user" },
    { "name": "ORDERS_DB_HOST", "value": "mariadb-apps.ngris-appdb.svc.cluster.local", "is_secret": false, "environment": "all", "source": "database",
      "connection_uuid": "019c2a71-9a2d-7d06-8e41-3f7b2c9d0a58", "database_uuid": "019c2a41-7d3e-7b52-a1c4-5e9f0b3d6a18", "database_name": "orders-db",
      "database_user_uuid": "019c2a41-7d40-7e15-9b63-2f8c4d1a7e95", "database_user_name": "app" },
    { "name": "ORDERS_DB_PASSWORD", "value": "", "is_secret": true, "environment": "all", "source": "database",
      "connection_uuid": "019c2a71-9a2d-7d06-8e41-3f7b2c9d0a58", "database_uuid": "019c2a41-7d3e-7b52-a1c4-5e9f0b3d6a18", "database_name": "orders-db",
      "database_user_uuid": "019c2a41-7d40-7e15-9b63-2f8c4d1a7e95", "database_user_name": "app" }
  ]
}

Set an Environment Variable

PUT /v1/applications/{uuid}/env

Create or update one variable. Mark sensitive values (API keys, tokens) as a secret — they're encrypted at rest and never returned again. For a running managed, full-stack, WordPress or function app the change applies right away: ngris restarts the app (applied: true). Otherwise it applies on the next deploy.

An empty value keeps an existing secret's value: a variable that is already a secret, saved again with is_secret: true and "value": "", keeps the value it has. So a secret can't be set to an empty value; delete the variable instead.

Request (application/json)

name string

Required. Must match [A-Za-z_][A-Za-z0-9_]*.

value string

The value to inject. Empty on a variable that is already a secret (with is_secret: true): its value is kept.

is_secret bool

true encrypts the value at rest and hides it from future reads.

environment string

production, preview or all (default). A value for one environment wins over the all value of the same name in that environment.

Errors

400

An invalid name or environment. On a managed, full-stack, WordPress or function app, names starting with DB_, DDL_ or WORDPRESS_DB_, and DATABASE_URL, are managed by ngris and refused.

409

env_reserved_by_database: a database connection of this app gives it this name (e.g. ORDERS_DB_HOST) in an overlapping environment; name echoes it. Disconnect the database, or connect it with another prefix, to use the name. Also quota_paused when the app is paused over your plan's limits.

Request
curl -X PUT "https://api.ngris.com/v1/applications/019be838-d261-7d9b-9499-71995a3a91c6/env" \
  -H "X-API-KEY: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{"name":"VITE_API_URL","value":"https://api.example.com","is_secret":false}'

Response — 200 OK
{ "status": "ok", "name": "VITE_API_URL", "environment": "all", "applied": false }

Response — 409 (reserved by a database connection)
{
  "error": "ORDERS_DB_HOST is set by a database connection of this app. Disconnect the database (or connect it with another prefix) to use this name.",
  "code": "env_reserved_by_database",
  "name": "ORDERS_DB_HOST"
}

Delete an Environment Variable

DELETE /v1/applications/{uuid}/env/{name}

Remove one variable by name; ?environment=production|preview|all (default all) picks which one. Returns 204 No Content, or 404 “No variable with that name in the <environment> environment” when there is nothing to delete (nothing changes, nothing restarts). A running managed, full-stack, WordPress or function app restarts to apply it; otherwise it takes effect on the next deploy. Variables from a database connection can't be deleted here: disconnect the database.

Request
curl -X DELETE \
  "https://api.ngris.com/v1/applications/019be838-d261-7d9b-9499-71995a3a91c6/env/VITE_API_URL" \
  -H "X-API-KEY: <your_api_key>"