---
title: "Set environment variable"
method: PUT
path: "/api/v1/apps/services/{service_id}/env"
tags: ["Raff Apps"]
---

# Set environment variable

`PUT /api/v1/apps/services/{service_id}/env`

Create or update one variable. By default the change rolls out to
running replicas. Set `redeploy: false` to defer it to the next deploy.

A variable with `scope` of `build` or `both` is passed to the image
build, so changing it triggers a rebuild rather than a restart.

## Path parameters

- `service_id` string, required

## Request body

- object
  - `key` string, required
  - `value` string, required
  - `is_secret` boolean
  - `scope` 'runtime' | 'build' | 'both' — Where the value is injected. Use `build` or `both` for values a framework inlines at build time (NEXT_PUBLIC_*, VITE_*, REACT_APP_*, PUBLIC_*); changing one rebuilds the image instead of restarting replicas.
  - `redeploy` boolean

## Response `200`

Variable set

- object
  - `success` boolean
  - `env_vars` AppEnvVar[]
    - `key` string
    - `value` string — Empty for secrets unless fetched via the reveal endpoint
    - `is_secret` boolean
    - `is_system` boolean — Managed by the platform (e.g. bindings) — read-only
    - `scope` 'runtime' | 'build' | 'both' — Where the value is injected. `runtime` reaches the running container only. `build` reaches the image build only. `both` reaches each. Frameworks that inline configuration at build time need `build` or `both` — Next.js `NEXT_PUBLIC_*`, Vite `VITE_*`, Create React App `REACT_APP_*`, SvelteKit and Astro `PUBLIC_*`. A runtime-only value is not visible to those builds and ships as an empty string. Changing a build-scoped variable rebuilds the image rather than restarting replicas, so it takes a full build to take effect. Build arguments are recoverable from image history for any `ARG` the Dockerfile declares, so a build-scoped value is not confidential inside the image. Prefer `runtime` for credentials.
  - `deployment_id` string, uuid

## Other responses

- `400` — Invalid request parameters
- `401` — Authentication required

## Changes

- **2026-09-02** `a8f47da1ca32` — 2 info
  - added the new optional request property `scope`
  - added the optional property `env_vars/items/scope` to the response with the `200` status
- **2026-08-20** `efd3c11c5c92` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/rafftechnologies/apis/raff-api/changes/api/v1/apps/services/:service_id/env/put.md)

---

[API](https://skmtc.dev/rafftechnologies/apis/raff-api.md) · [All operations](https://skmtc.dev/rafftechnologies/apis/raff-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/rafftechnologies/raff-api/revisions/a8f47da1ca32/schema)