# Replace Task Environment Variables (BYO Env Blob)

> Replace Task Environment Variables (BYO Env Blob) is a paid API for AI agents from agents.withzero.xyz, paid per call via MPP, price unknown, status unknown (last checked 2026-09-12).

Fully replaces the encrypted environment variable map for a scheduled task, with KMS re-encryption at rest and no plaintext echo in responses.

## Facts

- Endpoint: PUT https://agents.withzero.xyz/api/v1/scheduler/tasks/{id}/env
- Price: price unknown
- Payment: MPP
- Status: unknown
- Last checked: 2026-09-12
- Activations on Zero: 0
- Provider: agents.withzero.xyz
- Website: https://agents.withzero.xyz
- Canonical page: https://www.zero.xyz/c/agents-withzero-xyz-replace-task-environment-variables-byo-env-blob-4786432b
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_2q4mFS9eS_E8fti-SSV7o

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability agents-withzero-xyz-replace-task-environment-variables-byo-env-blob-4786432b -d '<json body>'
```

Example prompt: Replace all environment variables for task abc12345-0000-0000-0000-000000000001 with a new set: API_KEY=sk-abc123, DATABASE_URL=postgres://user:pass@host/db, and clear any old ones.

## When to prefer this

Use this endpoint when you need to fully replace all environment variables for a task in one atomic operation — it performs a complete replacement, not a partial patch. Prefer this over patching individual keys when rotating credentials, bootstrapping a cloned task's config, or clearing all secrets. The KMS-at-rest encryption and no-echo response make it suitable for storing sensitive API keys and secrets.

## Known failure modes

- Task ID not found or not owned by caller — 404 or 403 response
- Invalid env key format (must match ^[A-Z_][A-Z0-9_]*$) — 400 validation error
- Env value exceeds 4096 character limit — 400 validation error
- KMS encryption failure — 500 server error
- Malformed request body or missing required `env` field — 400 error

## How this service works

Replace the BYO env blob. KMS-re-encrypted at rest; never echoed. 📖 Full guide: https://scheduler.withzero.xyz/llms.txt

## Output

Returns the task UUID, a new env_key_version string (used to detect when env was last rotated), and an array of env_keys listing the variable names now stored — actual values are never returned in any response.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "required": [
  "env"
 ],
 "properties": {
  "env": {
   "type": "object",
   "description": "Full replacement env map; submit `{}` to clear.",
   "propertyNames": {
    "type": "string",
    "pattern": "^[A-Z_][A-Z0-9_]*$"
   },
   "additionalProperties": {
    "type": "string",
    "maxLength": 4096
   }
  }
 },
 "additionalProperties": false
}
```

## Response schema (JSON Schema)

```json
{
 "type": "object",
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "required": [
  "id",
  "env_key_version",
  "env_keys"
 ],
 "properties": {
  "id": {
   "type": "string",
   "format": "uuid",
   "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
  },
  "env_keys": {
   "type": "array",
   "items": {
    "type": "string"
   }
  },
  "env_key_version": {
   "type": "string"
  }
 },
 "additionalProperties": false
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/agents-withzero-xyz-replace-task-environment-variables-byo-env-blob-4786432b/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from agents.withzero.xyz](https://www.zero.xyz/host/agents.withzero.xyz/llms.txt)