OrbitsDocs
esc
    Open Orbits
    API reference · DeployEnvironment variables

    Environment variables

    A project's variables per environment: list, add, change, delete and restore them, reveal one, or pull them all.

    Each variable is a key with a value for one or more environments (production, preview, development). Values are encrypted at rest and never returned by a list: reveal one, or pull an environment's, with a full token. A read token never reads values. A change applies to deployments created after it: redeploy to use it. See Environment variables.

    The environment variable object

    Fields

    • idstringrequired
    • keystringrequired
    • valuestring or nullrequired

      Only for a non-sensitive variable whose key is meant for the browser (NEXT_PUBLIC_, NUXT_PUBLIC_, PUBLIC_, VITE_, REACT_APP_, EXPO_PUBLIC_ prefix, or a _PUBLIC_KEY suffix). Otherwise null; use POST .../env/{key}/reveal.

    • sensitivebooleanrequired
    • environmentsarray of stringrequired
    • pending_redeploybooleanrequired

      Changed since the latest deployment; shows the "New" tag.

    • created_atstringrequired
    • updated_atstringrequired
    • updated_byobjectrequired
      Show 2 child fields
      • idstringrequired
      • namestringrequired

    List variables

    The Environment variables page: one row per key, with the environments it applies to. Values are encrypted at rest. A row's value is returned only for a variable that is not sensitive and whose key is meant for the browser (it starts with NEXT_PUBLIC_, NUXT_PUBLIC_, PUBLIC_, VITE_, REACT_APP_ or EXPO_PUBLIC_, or ends with _PUBLIC_KEY); every other value is null and the page shows dots. A sensitive variable can never be read back by anyone (the dialog says "Nobody can read it back, only replace it"), so show no eye icon, Reveal value or Copy value for it. For any other variable, "Reveal value" and "Copy value" call POST /v1/teams/{team}/projects/{project}/env/{key}/reveal.

    total is the number of variables that match the filters ("10 variables"). last_changed feeds the pull dialog ("Last changed yesterday by Shady Asaolu"); it is null when there are none. redeploy drives the blue banner ("You changed 1 variable. Redeploy so production picks it up."): required is true when something changed since the project's latest deployment and changed counts those variables; each row's pending_redeploy marks the ones to highlight (the "New" tag). Until deployments exist, redeploy.required is always false.

    Permissions: Any team member, including viewers. A non-member gets 404.

    GET/v1/teams/{team}/projects/{project}/env
    Read or full tokenReturns200OK

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    Path parameters

    • teamstringrequired

      Team slug or team_ id.

    • projectstringrequired

      Project slug or prj_ id.

    Query parameters

    • limitinteger

      From 1 to 100. Defaults to 25.

    • cursorstring
    • environmentstring

      Only variables that apply to this environment.

      One of production, preview, development.

    • qstring

      Substring of the key.

    Response 200

    Variables.
    • next_cursorstring or null
    • itemsarray of EnvVarrequired
      Show 9 child fields
      • idstringrequired
      • keystringrequired
      • valuestring or nullrequired

        Only for a non-sensitive variable whose key is meant for the browser (NEXT_PUBLIC_, NUXT_PUBLIC_, PUBLIC_, VITE_, REACT_APP_, EXPO_PUBLIC_ prefix, or a _PUBLIC_KEY suffix). Otherwise null; use POST .../env/{key}/reveal.

      • sensitivebooleanrequired
      • environmentsarray of stringrequired
      • pending_redeploybooleanrequired

        Changed since the latest deployment; shows the "New" tag.

      • created_atstringrequired
      • updated_atstringrequired
      • updated_byobjectrequired
        Show 2 child fields
        • idstringrequired
        • namestringrequired
    • totalintegerrequired

      Variables matching the filters.

    • last_changednull or objectrequired
      Show 2 child fields
      • atstringrequired
      • byobjectrequired
        Show 2 child fields
        • idstringrequired
        • namestringrequired
    • redeployobjectrequired
      Show 2 child fields
      • requiredbooleanrequired
      • changedintegerrequired

    Errors

    • 404Not found, or not visible to the caller (the two are indistinguishable on purpose).

    Every code is explained in Errors.

    curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app/env" \
      -H "Authorization: Bearer $ORBITS_TOKEN"
    Response 200
    {
      "next_cursor": null,
      "items": [
        {
          "id": "var_01J9ZK3Q",
          "key": "key",
          "value": null,
          "sensitive": false,
          "environments": [
            "production"
          ],
          "pending_redeploy": false,
          "created_at": "2026-11-10T09:30:00Z",
          "updated_at": "2026-11-10T09:30:00Z",
          "updated_by": {
            "id": "id",
            "name": "my-app"
          }
        }
      ],
      "total": 1,
      "last_changed": {
        "at": "2026-11-10T09:30:00Z",
        "by": {
          "id": "id",
          "name": "my-app"
        }
      },
      "redeploy": {
        "required": false,
        "changed": 1
      }
    }

    Add variables, or import a .env file

    Saves one or more variables. The Add variable dialog sends one with the default on_conflict: fail: a key that already exists is 409 and nothing is saved (use Edit instead). The Import .env dialog sends every parsed line with on_conflict: replace, which replaces the value and environments of keys that already exist, as its warning says ("Importing replaces its value in the environments you pick"). The dialog parses the file in the browser; show the conflicts from the list you already loaded. sensitive defaults to true, as the Sensitive checkbox does.

    A project can have at most 1,000 variables. An import that would go over (replacing existing keys adds none) is 422 on variables and saves nothing. The request body is at most 1 MiB, which the gateway enforces on every request (413), so a very large import must be split.

    The new values apply to deployments created afterwards; redeploy_required says whether the banner should show.

    Permissions: Owner, admin or member of the team. Viewers get 403. A non-member gets 404.

    POST/v1/teams/{team}/projects/{project}/env
    Full tokenNeeds Idempotency-KeyReturns201Created

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    • Idempotency-Keystringrequired

      A new value, such as a UUID, for each change. Resend with the same value and body to retry safely.

      From 8 to 128 characters.

    Path parameters

    • teamstringrequired

      Team slug or team_ id.

    • projectstringrequired

      Project slug or prj_ id.

    Body

    application/json
    • variablesarray of objectrequired

      At most 500 items.

      Show 4 child fields
      • keystringrequired

        At most 255 characters.

      • valuestringrequired

        May be empty; at most 32 KiB (32,768 bytes) once encoded. Never returned except as described on EnvVar.value.

        At most 32768 characters.

      • environmentsarray of string

        Used by Production and Preview unless the user picks otherwise.

      • sensitiveboolean

        Write-only: nobody can read the value back, only replace it.

        Defaults to true.

    • on_conflictstring

      fail (Add variable): a key that already exists is 409 and nothing is saved. replace (Import .env): existing keys get the new value and environments.

      One of fail, replace. Defaults to fail.

    Response 201

    Saved.
    • itemsarray of EnvVarrequired
      Show 9 child fields
      • idstringrequired
      • keystringrequired
      • valuestring or nullrequired

        Only for a non-sensitive variable whose key is meant for the browser (NEXT_PUBLIC_, NUXT_PUBLIC_, PUBLIC_, VITE_, REACT_APP_, EXPO_PUBLIC_ prefix, or a _PUBLIC_KEY suffix). Otherwise null; use POST .../env/{key}/reveal.

      • sensitivebooleanrequired
      • environmentsarray of stringrequired
      • pending_redeploybooleanrequired

        Changed since the latest deployment; shows the "New" tag.

      • created_atstringrequired
      • updated_atstringrequired
      • updated_byobjectrequired
        Show 2 child fields
        • idstringrequired
        • namestringrequired
    • createdintegerrequired
    • replacedintegerrequired
    • redeploy_requiredbooleanrequired

    Errors

    • 403Authenticated but not allowed in this team.
    • 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
    • 409The request conflicts with current state.
    • 422Validation failed, or the Idempotency-Key was reused with a different body.

    Every code is explained in Errors.

    curl -X POST "https://api.theorbits.app/v1/teams/my-team/projects/my-app/env" \
      -H "Authorization: Bearer $ORBITS_TOKEN" \
      -H "Idempotency-Key: $(uuidgen)" \
      -H "Content-Type: application/json" \
      -d '{
        "variables": [
          {
            "key": "STRIPE_SECRET_KEY",
            "value": "value",
            "environments": [
              "production"
            ],
            "sensitive": true
          }
        ]
      }'
    Response 201
    {
      "items": [
        {
          "id": "var_01J9ZK3Q",
          "key": "key",
          "value": null,
          "sensitive": false,
          "environments": [
            "production"
          ],
          "pending_redeploy": false,
          "created_at": "2026-11-10T09:30:00Z",
          "updated_at": "2026-11-10T09:30:00Z",
          "updated_by": {
            "id": "id",
            "name": "my-app"
          }
        }
      ],
      "created": 1,
      "replaced": 1,
      "redeploy_required": false
    }

    Change a value or its environments

    The Edit dialog: the key is read-only ("To rename a key, add a new one and delete this one"). Send value only when the user typed a new one; leave it out to change just the environments. Send environments only when the checkboxes changed. At least one of them is required. Whether a variable is sensitive cannot be changed here.

    Permissions: Owner, admin or member of the team. Viewers get 403. A non-member gets 404.

    PATCH/v1/teams/{team}/projects/{project}/env/{key}
    Full tokenReturns200OK

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    Path parameters

    • teamstringrequired

      Team slug or team_ id.

    • projectstringrequired

      Project slug or prj_ id.

    • keystringrequired

    Body

    application/json
    • valuestring

      At most 32768 characters.

    • environmentsarray of string

    Response 200

    Saved.
    • itemEnvVarrequired
      Show 9 child fields
      • idstringrequired
      • keystringrequired
      • valuestring or nullrequired

        Only for a non-sensitive variable whose key is meant for the browser (NEXT_PUBLIC_, NUXT_PUBLIC_, PUBLIC_, VITE_, REACT_APP_, EXPO_PUBLIC_ prefix, or a _PUBLIC_KEY suffix). Otherwise null; use POST .../env/{key}/reveal.

      • sensitivebooleanrequired
      • environmentsarray of stringrequired
      • pending_redeploybooleanrequired

        Changed since the latest deployment; shows the "New" tag.

      • created_atstringrequired
      • updated_atstringrequired
      • updated_byobjectrequired
        Show 2 child fields
        • idstringrequired
        • namestringrequired
    • redeploy_requiredbooleanrequired

    Errors

    • 403Authenticated but not allowed in this team.
    • 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
    • 422Validation failed, or the Idempotency-Key was reused with a different body.

    Every code is explained in Errors.

    curl -X PATCH "https://api.theorbits.app/v1/teams/my-team/projects/my-app/env/DATABASE_URL" \
      -H "Authorization: Bearer $ORBITS_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "value": "value",
        "environments": [
          "production"
        ]
      }'
    Response 200
    {
      "item": {
        "id": "var_01J9ZK3Q",
        "key": "key",
        "value": null,
        "sensitive": false,
        "environments": [
          "production"
        ],
        "pending_redeploy": false,
        "created_at": "2026-11-10T09:30:00Z",
        "updated_at": "2026-11-10T09:30:00Z",
        "updated_by": {
          "id": "id",
          "name": "my-app"
        }
      },
      "redeploy_required": false
    }

    Delete a variable

    The Delete dialog ("Type STRIPE_SECRET_KEY to confirm"; the typed confirmation is checked in the browser). The variable is hidden at once but its encrypted value is kept until restorable_until (10 minutes), so the toast's Undo can call POST /v1/teams/{team}/projects/{project}/env/{key}/restore. Deployments created after the delete no longer get it.

    Permissions: Owner, admin or member of the team. Viewers get 403. A non-member gets 404.

    DELETE/v1/teams/{team}/projects/{project}/env/{key}
    Full tokenReturns200OK

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    Path parameters

    • teamstringrequired

      Team slug or team_ id.

    • projectstringrequired

      Project slug or prj_ id.

    • keystringrequired

    Response 200

    Deleted, and restorable until restorable_until.
    • keystringrequired
    • restorable_untilstringrequired
    • redeploy_requiredbooleanrequired

    Errors

    • 403Authenticated but not allowed in this team.
    • 404Not found, or not visible to the caller (the two are indistinguishable on purpose).

    Every code is explained in Errors.

    curl -X DELETE "https://api.theorbits.app/v1/teams/my-team/projects/my-app/env/DATABASE_URL" \
      -H "Authorization: Bearer $ORBITS_TOKEN"
    Response 200
    {
      "key": "key",
      "restorable_until": "2026-11-10T09:30:00Z",
      "redeploy_required": false
    }

    Undo a delete

    The Undo button on the "deleted" toast. It brings the variable back with the value and environments it had. 404 means the 10 minutes have passed (or it was never deleted); 409 means a variable with that key exists again.

    Permissions: Owner, admin or member of the team. Viewers get 403. A non-member gets 404.

    POST/v1/teams/{team}/projects/{project}/env/{key}/restore
    Full tokenNeeds Idempotency-KeyReturns200OK

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    • Idempotency-Keystringrequired

      A new value, such as a UUID, for each change. Resend with the same value and body to retry safely.

      From 8 to 128 characters.

    Path parameters

    • teamstringrequired

      Team slug or team_ id.

    • projectstringrequired

      Project slug or prj_ id.

    • keystringrequired

    Response 200

    Restored.
    • itemEnvVarrequired
      Show 9 child fields
      • idstringrequired
      • keystringrequired
      • valuestring or nullrequired

        Only for a non-sensitive variable whose key is meant for the browser (NEXT_PUBLIC_, NUXT_PUBLIC_, PUBLIC_, VITE_, REACT_APP_, EXPO_PUBLIC_ prefix, or a _PUBLIC_KEY suffix). Otherwise null; use POST .../env/{key}/reveal.

      • sensitivebooleanrequired
      • environmentsarray of stringrequired
      • pending_redeploybooleanrequired

        Changed since the latest deployment; shows the "New" tag.

      • created_atstringrequired
      • updated_atstringrequired
      • updated_byobjectrequired
        Show 2 child fields
        • idstringrequired
        • namestringrequired
    • redeploy_requiredbooleanrequired

    Errors

    • 403Authenticated but not allowed in this team.
    • 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
    • 409The request conflicts with current state.

    Every code is explained in Errors.

    curl -X POST "https://api.theorbits.app/v1/teams/my-team/projects/my-app/env/DATABASE_URL/restore" \
      -H "Authorization: Bearer $ORBITS_TOKEN" \
      -H "Idempotency-Key: $(uuidgen)"
    Response 200
    {
      "item": {
        "id": "var_01J9ZK3Q",
        "key": "key",
        "value": null,
        "sensitive": false,
        "environments": [
          "production"
        ],
        "pending_redeploy": false,
        "created_at": "2026-11-10T09:30:00Z",
        "updated_at": "2026-11-10T09:30:00Z",
        "updated_by": {
          "id": "id",
          "name": "my-app"
        }
      },
      "redeploy_required": false
    }

    Reveal a value

    "Reveal value" and "Copy value" (and the eye icon) on a row. It is a POST because every reveal is recorded as a project.env.revealed event with who asked and which key, never the value. A sensitive variable answers 409: it can never be read back. The response is never cached or replayed: this call ignores Idempotency-Key, so every call reads the value again and is recorded.

    Permissions: Owner, admin or member of the team. Viewers get 403. A non-member gets 404.

    POST/v1/teams/{team}/projects/{project}/env/{key}/reveal
    Full tokenReturns200OK

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    Path parameters

    • teamstringrequired

      Team slug or team_ id.

    • projectstringrequired

      Project slug or prj_ id.

    • keystringrequired

    Response 200

    The value.
    • keystringrequired
    • valuestringrequired

    Errors

    • 403Authenticated but not allowed in this team.
    • 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
    • 409The request conflicts with current state.

    Every code is explained in Errors.

    curl -X POST "https://api.theorbits.app/v1/teams/my-team/projects/my-app/env/DATABASE_URL/reveal" \
      -H "Authorization: Bearer $ORBITS_TOKEN"
    Response 200
    {
      "key": "key",
      "value": "value"
    }

    Download values for local development (orbits env pull)

    What orbits env pull calls to write .env.local. It returns the values of every variable that applies to environment, except sensitive ones, which nobody can read back: their keys are listed in skipped_sensitive so the CLI can tell the user. Every pull is recorded as a project.env.pulled event. The response is never cached or replayed: this call ignores Idempotency-Key, so every call reads the values again and is recorded. The dashboard only shows the pull dialog; it does not call this endpoint.

    Permissions: Owner, admin or member of the team. Viewers get 403. A non-member gets 404.

    POST/v1/teams/{team}/projects/{project}/env/pull
    Full tokenReturns200OK

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    Path parameters

    • teamstringrequired

      Team slug or team_ id.

    • projectstringrequired

      Project slug or prj_ id.

    Body

    application/json
    • environmentstringrequired

      One of production, preview, development.

    Response 200

    Values for the environment.
    • environmentstringrequired

      One of production, preview, development.

    • variablesobjectrequired
    • skipped_sensitivearray of stringrequired

      Keys left out because nobody can read them back.

    Errors

    • 403Authenticated but not allowed in this team.
    • 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
    • 422Validation failed, or the Idempotency-Key was reused with a different body.

    Every code is explained in Errors.

    curl -X POST "https://api.theorbits.app/v1/teams/my-team/projects/my-app/env/pull" \
      -H "Authorization: Bearer $ORBITS_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "environment": "production"
      }'
    Response 200
    {
      "environment": "production",
      "variables": {},
      "skipped_sensitive": [
        "skipped-sensitive"
      ]
    }

    Was this page helpful?

    Updated