Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.autosana.ai/llms.txt

Use this file to discover all available pages before exploring further.

These endpoints let you browse environments and manage their environment variables programmatically. Use them to bulk-import config from another secrets manager, keep credentials in sync with CI, or build dashboards on top of Autosana. All requests require an API key in the X-API-Key header. See API Reference for authentication and the standard 401 / 403 / 429 / 500 error shapes shared by every endpoint on this page.
Secret values are write-only through the API. When is_secret=true, the value is stored encrypted in vault and is never returned by any read endpoint — list and get responses always render secret values as "***". There is no API path to retrieve a decrypted secret.
Environments themselves (create / rename / delete) are managed from the dashboard. The API surface here covers env vars and read access to the environments that contain them.

​
List Environments

Returns every environment in your organization with its env vars nested. Plaintext values come back in full; secret values are masked as "***".
GET /api/v1/environments — Returns 200 OK

​
Example Request

curl -X GET https://backend.autosana.ai/api/v1/environments \
  -H "X-API-Key: YOUR_API_KEY"

​
Response Fields

​
environments
array
List of environments.
​
count
integer
Total number of environments returned.

​
Example Response

{
  "environments": [
    {
      "id": "770e8400-e29b-41d4-a716-446655440099",
      "name": "Staging",
      "env_vars": [
        {
          "id": "880e8400-e29b-41d4-a716-446655440010",
          "environment_id": "770e8400-e29b-41d4-a716-446655440099",
          "key": "API_TOKEN",
          "value": "***",
          "is_secret": true,
          "description": null,
          "created_at": "2026-01-15T10:30:00Z",
          "updated_at": "2026-01-15T10:30:00Z"
        },
        {
          "id": "880e8400-e29b-41d4-a716-446655440011",
          "environment_id": "770e8400-e29b-41d4-a716-446655440099",
          "key": "API_URL",
          "value": "https://staging.api.example.com",
          "is_secret": false,
          "description": "Staging API base URL",
          "created_at": "2026-01-15T10:31:00Z",
          "updated_at": "2026-01-15T10:31:00Z"
        }
      ]
    }
  ],
  "count": 1
}

​
Create Env Var

POST /api/v1/env-vars — Returns 201 Created. Returns 409 Conflict if an env var with the same key already exists on this environment.

​
Request Body

​
environment_id
string
required
UUID of the environment this variable belongs to.
​
key
string
required
Variable name (1–255 characters). Referenced from flows and curl hooks as ${env:KEY}.
​
value
string
required
Variable value — must be a non-empty string. Empty values are rejected with 422 because they’re indistinguishable from “unset” at consumption time. For secrets, this is written to vault and never returned by any read endpoint.
​
description
string
Optional human-readable note.
​
is_secret
boolean
Defaults to false. When true, the value is stored encrypted in vault and is never readable back through the API.

​
Example Request (plaintext)

curl -X POST https://backend.autosana.ai/api/v1/env-vars \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "environment_id": "770e8400-e29b-41d4-a716-446655440099",
    "key": "API_URL",
    "value": "https://staging.api.example.com",
    "description": "Staging API base URL"
  }'

​
Example Request (secret)

curl -X POST https://backend.autosana.ai/api/v1/env-vars \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "environment_id": "770e8400-e29b-41d4-a716-446655440099",
    "key": "API_TOKEN",
    "value": "abc123...super-secret",
    "is_secret": true
  }'

​
Example Response

{
  "id": "880e8400-e29b-41d4-a716-446655440010",
  "environment_id": "770e8400-e29b-41d4-a716-446655440099",
  "key": "API_TOKEN",
  "value": "***",
  "is_secret": true,
  "description": null,
  "created_at": "2026-01-15T10:30:00Z",
  "updated_at": "2026-01-15T10:30:00Z"
}

​
Get Env Var

GET /api/v1/env-vars/{env_var_id} — Returns 200 OK with the same shape as items in List Environments’ env_vars, or 404 if the var does not exist. Secret values are returned as "***".
​
env_var_id
string
required
UUID of the env var.
curl -X GET https://backend.autosana.ai/api/v1/env-vars/ENV_VAR_UUID \
  -H "X-API-Key: YOUR_API_KEY"

​
Update Env Var

Update an env var. Only provided fields change; omitted fields are unchanged.
PATCH /api/v1/env-vars/{env_var_id} — Returns 200 OK. 400 if no recognized fields are provided. 404 if the var does not exist. 409 if renaming key collides with another env var in the same environment. 422 for invalid transitions (see below).
No-op PATCHes don’t bump updated_at. If the body resolves to no actual state change — e.g. {"is_secret": true} on a row that’s already a secret — the endpoint returns the unchanged row without writing to the DB. Don’t rely on PATCH to act as a heartbeat.
​
env_var_id
string
required
UUID of the env var.
​
key
string
New variable name (1–255 characters). Note: any flows or curl hooks that reference the old name as ${env:OLD_KEY} must be updated in lockstep — there is no automatic rewrite. Collisions with another env var in the same environment return 409.
​
value
string
New value. Omit to keep the existing value unchanged. Required when changing is_secret in either direction (the API never re-uses the existing value across a secret/plaintext transition). null is treated as “no change”, not “clear” — there is no way to clear a value without deleting the row.
​
description
string | null
New description. Pass "" or null to explicitly clear (this is the only field where null clears rather than meaning “no change”).
​
is_secret
boolean
Move the var between plaintext and vault-encrypted storage. Switching the flag in either direction requires value.

​
Secret transition rules

Existing stateRequestResult
Plaintextvalue: "new"Plaintext value rewritten in place.
Plaintextis_secret: true, no value422 — promoting to secret requires a value.
Plaintextis_secret: true, value: "secret-x"New vault row written; row repointed to it.
Secretvalue: "rotated"New vault row written, old one cleaned up after the row is repointed.
Secretis_secret: false, no value422 — demoting to plaintext requires a value.
Secretis_secret: false, value: "plain"Old vault row cleaned up, plaintext value written.

​
Example Request

# Rotate an existing secret
curl -X PATCH https://backend.autosana.ai/api/v1/env-vars/ENV_VAR_UUID \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "value": "new-rotated-secret-value" }'

# Promote a plaintext var to a secret
curl -X PATCH https://backend.autosana.ai/api/v1/env-vars/ENV_VAR_UUID \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "is_secret": true, "value": "secret-only-known-at-rotation" }'

​
Delete Env Var

Deletes the env var. If the var is a secret, its vault entry is cleaned up too.
DELETE /api/v1/env-vars/{env_var_id} — Returns 204 No Content, or 404 if the var does not exist.
​
env_var_id
string
required
UUID of the env var.
curl -X DELETE https://backend.autosana.ai/api/v1/env-vars/ENV_VAR_UUID \
  -H "X-API-Key: YOUR_API_KEY"
Deleting a variable will cause any flows or hooks that reference ${env:VARIABLE_NAME} to fail. Update or remove references before deleting.