---
title: "Create an agent environment variable"
method: POST
path: "/api/v1/agents/{agent}/agent_env_vars"
---

# Create an agent environment variable

`POST /api/v1/agents/{agent}/agent_env_vars`

Creates a new environment variable for the specified agent. The variable is
stored securely and the plaintext `value` is never returned after creation;
subsequent reads return a masked representation showing only the last four
characters.

The authenticated user must have access to the agent's parent app. Pass the
app scope via the `app` parameter when calling with an API key that is scoped
to a specific app. Each `key` must be unique within the agent; attempting to
create a duplicate key returns a validation error.

## Path parameters

- `agent` string, required

## Request body

- object
  - `description` string — Optional human-readable note describing what the variable is used for.
  - `key` string, required — Environment variable name, e.g. `WEBHOOK_SECRET`. Must be unique within the agent.
  - `value` string, required — Plaintext secret value to store. The value is encrypted at rest and never returned in full.

## Response `200`

Successful response

- AgentEnvVarMasked — An agent environment variable with its secret value masked for safe display in list and show responses.
  - `agent` string, required — ID of the agent this environment variable belongs to (`agt_...`).
  - `created_at` string, date-time — When the environment variable was created (ISO 8601).
  - `description` string — Optional human-readable note describing the purpose of this variable. `null` if not set.
  - `id` string, required — Environment variable ID (`anv_...`).
  - `key` string, required — Name of the environment variable as it appears in the agent's runtime.
  - `masked_value` string, required — Redacted representation of the secret value. The last four characters are preserved; all preceding characters are replaced with `****`. Returns `****` when the value is absent or four characters or fewer.
  - `updated_at` string, date-time — When the environment variable was last updated (ISO 8601).

## Other responses

- `401` — Unauthorized
- `403` — App-scoped token required. Use a token scoped to the target app.; Forbidden
- `404` — Not found
- `422` — Validation failed

---

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