v1

latestOpenAPI 3.0.02026-08-04891301.4 MB

Create an agent environment variable

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.

post/api/v1/agents/{agent}/agent_env_vars

Path parameters

agentstring required

Agent ID (agt_...). The agent must belong to an app the caller can access.

Request body

descriptionstring

Optional human-readable note describing what the variable is used for.

keystring required

Environment variable name, e.g. WEBHOOK_SECRET. Must be unique within the agent.

valuestring required

Plaintext secret value to store. The value is encrypted at rest and never returned in full.

Example request

{
  "description": "An example description.",
  "key": "string",
  "value": "string"
}

Response

Successful response

agentstring required

ID of the agent this environment variable belongs to (agt_...).

created_atstring date-time

When the environment variable was created (ISO 8601).

descriptionstring

Optional human-readable note describing the purpose of this variable. null if not set.

idstring required

Environment variable ID (anv_...).

keystring required

Name of the environment variable as it appears in the agent's runtime.

masked_valuestring 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_atstring date-time

When the environment variable was last updated (ISO 8601).

Example response

{
  "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu",
  "created_at": "2024-01-01T00:00:00Z",
  "description": "An example description.",
  "id": "anv_0aBcDeFgHiJkLmNoPqRsTu",
  "key": "OPENAI_API_KEY",
  "masked_value": "****1234",
  "updated_at": "2024-01-01T00:00:00Z"
}