REST API v1

Use the REST API to load resolved environment values at runtime. The base URL is https://api.envlet.dev.

Authentication

Send your environment token as a bearer token on every request:

curl --fail-with-body \
  --request GET \
  --url "https://api.envlet.dev/v1/values" \
  --header "Authorization: Bearer $ENVLET_TOKEN"

The token identifies one project environment and one identity. Envlet applies that identity’s policy before it returns any values. Shared values stay unchanged, overrides replace shared values, and withheld keys are absent.

Get variable names

GET /v1/names returns every variable name in the token environment. The withheld array identifies names that the token cannot resolve. Both arrays are sorted, and the response does not contain values.

curl --fail-with-body \
  --request GET \
  --url "https://api.envlet.dev/v1/names" \
  --header "Authorization: Bearer $ENVLET_TOKEN"

A successful response has this shape:

{
  "names": ["DATABASE_URL", "PORT"],
  "withheld": [],
  "schema": {
    "DATABASE_URL": { "type": "url", "required": true, "enumValues": [] },
    "PORT": { "type": "integer", "required": false, "enumValues": [] }
  }
}

The schema covers the full environment, including withheld names. This metadata request does not create a resolution audit record.

Get all values

GET /v1/values returns every value that the token identity may read.

curl --fail-with-body \
  --request GET \
  --url "https://api.envlet.dev/v1/values" \
  --header "Authorization: Bearer $ENVLET_TOKEN"

A successful JSON response has this shape:

{
  "values": { "PORT": "8080" },
  "schema": {
    "PORT": { "type": "integer", "required": true, "enumValues": [] },
    "OPTIONAL_KEY": { "type": "string", "required": false, "enumValues": [] }
  }
}

The values object maps each environment variable name to its resolved wire string. The schema object contains the full environment schema. A withheld key is absent from values but remains in schema. An override appears in place of the shared value.

Dotenv format

Set the format query parameter to dotenv to get a text/plain dotenv body.

curl --fail-with-body \
  --request GET \
  --url "https://api.envlet.dev/v1/values?format=dotenv" \
  --header "Authorization: Bearer $ENVLET_TOKEN"

The response contains one KEY=value assignment per line. Use format=json or omit the parameter to get the JSON response. Any other format value returns invalid_request.

Get one value

GET /v1/values/:name returns one resolved environment value. Replace :name with the variable name.

curl --fail-with-body \
  --request GET \
  --url "https://api.envlet.dev/v1/values/DATABASE_URL" \
  --header "Authorization: Bearer $ENVLET_TOKEN"

A successful response has this shape:

{ "name": "PORT", "value": "8080", "schema": { "type": "integer", "required": true, "enumValues": [] } }

The endpoint returns 404 not_found when the variable is absent. It returns the same response when the identity’s policy withholds the variable. This rule prevents the identity from learning whether a withheld variable exists.

Variable schemas

The type is string, integer, number, boolean, url, json, or enum. Enum variables require unique, non-empty enumValues. The required setting defaults to true.

A create or update request that does not match the schema returns 400 invalid_request. Its message contains the variable name and one code: not_integer, not_number, not_boolean, not_url, not_json, or not_in_enum. The message never contains the value.

Errors

Errors use this JSON envelope:

{ "error": { "code": "unauthorized", "message": "bearer token is invalid" } }

Use the HTTP status for request flow and the code for program logic. Expired tokens have a separate code so your system can alert before you replace the token.

HTTP status	Code	Meaning
401	unauthorized	The bearer token is missing or invalid.
401	token_expired	The bearer token has expired.
404	not_found	The requested value is absent or withheld.
400	invalid_request	The request is invalid, such as an unsupported format value.