Environment Variables

The environments of the Environment Variables app. Resolve the variables of an environment, names only or with values, import an env file, and run a provider sync. The orgorg CLI uses these endpoints for its env commands.

Working with an AI agent?or point it at the Environment Variables markdown or the full-API markdown.

Resolve an environment

GET

/api/v1/env/resolve

The variables of one environment of the Environment Variables app, resolved along its parent chain. Without reveal, the names and their defining environment. With reveal=1, the values too: the store decrypts them, logs the read to your token, and the response is never cached. With key, only the named keys: the store decrypts only those, and the read log lists only those. An API token needs the env:read scope and Read access to the environment. A service token reads the one environment it is bound to, and needs no project and no environment. The response lists the services of the project, the consumers of its values, and each variable names the services of its key by slug. With service, only the keys of the named services: the CLI materializes what the command runs.

Parameter	Type	Description
project	string optional	The project slug, for example orgorg. Required with an API token.
environment	string optional	The environment slug, for example development. Required with an API token.
reveal	string optional	1 to include the values. Anything else returns names only.
key	string optional	Only this variable. Repeat the parameter for several variables, 100 at most.
service	string optional	Only the keys of this service, by slug. Repeat the parameter for several services.

Response:

{
  project: { slug: string; name: string };
  environment: { slug: string; name: string };
  variables: {
    key: string;
    value?: string;
    definedIn: string;
    public: boolean;
    services: string[]; // slugs of the services below
  }[];
  services: { slug: string; name: string }[];
}

List the environments of a project

GET

/api/v1/env/project

What the picker of `orgorg env run` shows: each environment of the project that you may read and that is not protected, with its parent, its owner, the number of values it sets itself, and the required names that it does not resolve. Also the key names of the project, and whether your token can make an environment. Nothing is decrypted. Needs an API token with the env:read scope.

Parameter	Type	Description
project	string required	The project slug, for example orgorg.
require	string optional	A variable name that your command needs. Repeat the parameter for several names, 100 at most. Each environment lists the names that it does not resolve.

Response:

{
  project: { slug: string; name: string };
  me: { profileId: number; name: string };
  devParent: string | null;
  canCreate: boolean;
  keyNames: string[];
  environments: {
    slug: string;
    name: string;
    parent: string | null;
    isParent: boolean;
    protected: boolean;
    owner: string | null;
    mine: boolean;
    ownValues: number;
    missing: string[];
  }[];
}

Make a development environment

POST

/api/v1/env/dev-environment

Make an environment of your own that extends development, with its first values, in one step. An environment is never empty: pass at least one entry of a key that the project has. A key that the project does not have sets nothing, and the response names it. When the step fails, nothing stays behind. Needs an API token with the env:dev scope and Read access to the development environment. This scope cannot write to an environment that exists.

Parameter	Type	Description
project	string required	The project slug, for example orgorg.
name	string required	The name of the new environment, for example dev-alex.
entries	object required	The first values: a list of { key, value } pairs of strings, 1 to 1000 entries.

Response:

{
  environment: { slug: string };
  written: number;
  unknown: string[];
}

Import an env file

POST

/api/v1/env/import

Write the entries of an env file into the environment of a service token. A key that exists gets the new value, and a new key is added for the CLI. The store encrypts each value, and the response carries counts only. Needs a service token as the bearer, not an API token.

Parameter	Type	Description
entries	object required	A list of { key, value } pairs of strings, 1 to 1000 entries.

Response:

{
  project: { slug: string };
  environment: { slug: string };
  created: number;
  updated: number;
  keysAdded: number;
}

Sync an environment with a provider

POST

/api/v1/env/sync

Run the sync target of one service in a service token environment. A pull imports the variables of the provider into the environment. A push sends the variables of the environment to the provider. The store does the provider work, and no value comes back. Needs a service token as the bearer, not an API token.

Parameter	Type	Description
direction	pull \| push required	pull or push.
service	string optional	The slug of the service, from the services of the resolve response. Required unless provider is given.
provider	vercel \| convex \| github \| cloudflare \| gcp optional	The transport kind, for a caller from before the services: it names the service the migration made for that kind.

Response:

// pull
{
  pulled: number;
  nameOnly: string[];
  created: number;
  updated: number;
  keysAdded: number;
}
// push
{
  pushed: number;
}