---
title: "PUT /v1/orgs/{orgId}/environments/{id}"
method: PUT
path: "/v1/orgs/{orgId}/environments/{id}"
tags: ["Orgs", "Environments"]
---

# PUT /v1/orgs/{orgId}/environments/{id}

`PUT /v1/orgs/{orgId}/environments/{id}`

## Request

- Base URL: `https://api.tessl.io`
- URL: `https://api.tessl.io/v1/orgs/{orgId}/environments/{id}`
- Auth: none declared

Replaces an organization environment's sealed value in place. The new `.env` payload is validated, sealed under the organization key, and never returned. `secretRefs` replaces the variables delivered from org secrets; when omitted, the environment holds no references afterwards, so it delivers only the payload's keys.

## Path parameters

- `orgId` string, uuid, required
- `id` string, uuid, required

## Headers

- `Authorization` string

## Request body

- object
  - `envFile` string: Raw `.env` file contents (`KEY=VALUE` per line). Blank lines and `#` comments are ignored. Mutually exclusive with `entries`.
  - `entries` object: Environment variables as a `KEY=VALUE` map. Mutually exclusive with `envFile`.
  - `secretRefs` object: Variables delivered from org secrets, as a map of variable name to the id of an org secret. A name cannot also carry a plain value.
  - `metadata` object
    - `description` string
    - `githubAccess` union: GitHub access granted to runs that use this environment. Defaults to read. pull-requests can comment on, edit, close, reopen and merge existing pull requests without the full write profile. It includes contents write, which GitHub requires to merge and which also allows pushing to, creating and deleting unprotected branches and tags, editing files, and managing releases.
      - 'none'
      - 'read'
      - 'pull-requests'
      - 'write'
    - `linearAccess` union: Linear access granted to runs that use this environment. Defaults to none.
      - 'none'
      - 'read'
      - 'write'
    - `readOtherRunLogs` boolean: Whether live runs using this environment may read other runs' transcripts in the same workspace. Defaults to false.
    - `projectMemory` union: Project memory access granted to runs that use this environment: read the memory of the run's own project, or read it and propose facts. Defaults to none.
      - 'none'
      - 'read'
      - 'write'
    - `actionTrigger` union: Whether runs that use this environment may trigger a declared action of the run's own project. Defaults to none.
      - 'none'
      - 'project'
    - `mcpServerNames` string[]: Names of MCP proxies to configure on this environment. Each must name an MCP server already registered and authorized where the environment is held: its workspace, or its organization. Naming an unknown or unauthorized server is a 400.

## Response `200`

Default Response

- object
  - `links` object, required
    - `self` string, uri, required
  - `data` object, required
    - `id` string, uuid, required
    - `type` 'environment', required
    - `attributes` object, required
      - `name` string, required
      - `metadata` object, nullable, required
        - `description` string
        - `fixtureSource` string
        - `managedBy` union
          - 'factory'
          - 'improve-development'
        - `factoryProjectId` string, uuid
        - `factoryStage` union
          - 'implement'
          - 'shepherd'
          - 'follow-ticket-changes'
        - `improveDevelopmentProjectId` string, uuid
        - `improveDevelopmentLoop` 'agent-retro'
        - `envVariableNames` string[]
        - `emptyKeyNames` string[]
        - `mcpServerNames` string[]
        - `githubAccess` union
          - 'none'
          - 'read'
          - 'pull-requests'
          - 'write'
        - `linearAccess` union
          - 'none'
          - 'read'
          - 'write'
        - `readOtherRunLogs` boolean
        - `actionTrigger` union
          - 'none'
          - 'project'
        - `projectMemory` union
          - 'none'
          - 'read'
          - 'write'
        - `movedFromWorkspaceId` string, uuid
        - `movedFromWorkspaceName` string
      - `keyNames` string[], required
      - `emptyKeyNames` string[], required
      - `mcpServerNames` string[], required
      - `githubAccess` union, required
        - 'none'
        - 'read'
        - 'pull-requests'
        - 'write'
      - `linearAccess` union, required
        - 'none'
        - 'read'
        - 'write'
      - `readOtherRunLogs` boolean, required
      - `projectMemory` union, required
        - 'none'
        - 'read'
        - 'write'
      - `actionTrigger` union
        - 'none'
        - 'project'
      - `createdBy` object, nullable, required
        - `id` string, uuid, required
        - `firstName` string, nullable, required
        - `lastName` string, nullable, required
      - `createdAt` string, date-time, required
      - `updatedAt` string, date-time, required
      - `orgId` string, uuid, required
      - `movedFromWorkspace` string, nullable, required: Name of the workspace that held this environment before it moved to the org. `null` for an environment created at org scope.
      - `boundProjects` object[], required
        - `id` string, uuid, required
        - `type` 'project', required
        - `attributes` object, required
          - `name` string, required
          - `workspaceId` string, uuid, required
          - `boundAt` string, date-time, required
      - `secretRefs` object[], required: Variables this environment delivers from org secrets. Every other name in `keyNames` carries a plain value.
        - `variableName` string, required
        - `secretId` string, uuid, required
      - `usage` object, required
        - `loopCount` integer, required: Unarchived Loops whose action names this environment.

## Other responses

- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found
- `500`: Internal Server Error

## Changes

- **2026-10-21** `a388ee77a37c`: 3 info
  - added the new optional request property `metadata/mcpServerNames`
  - added the new optional request property `secretRefs`
  - added the required property `data/attributes/secretRefs` to the response with the `200` status
- **2026-10-20** `5e5fdf4a6def`: 1 breaking, 1 warning, 1 info
  - the `data/attributes/metadata/anyOf[subschema #1]/improveDevelopmentLoop` response's property type changed from no type to `string` for status `200`
  - added the new `agent-retro` enum value to the `data/attributes/metadata/anyOf[subschema #1]/improveDevelopmentLoop` response property for the response status `200`
  - removed `subschema #1, subschema #2` from the `data/attributes/metadata/anyOf[subschema #1]/improveDevelopmentLoop` response property `anyOf` list for the response status `200`
- **2026-10-20** `e7b2825012cb`: 1 info
  - added `subschema #3` to the `data/attributes/metadata/anyOf[subschema #1]/factoryStage` response property `anyOf` list for the response status `200`
- …earlier changes not shown

[Operation history](https://skmtc.dev/tessl/apis/tessl-api/changes/v1/orgs/:orgId/environments/:id/put.md)

---

[API](https://skmtc.dev/tessl/apis/tessl-api.md) · [All operations](https://skmtc.dev/tessl/apis/tessl-api/llms.txt) · [OpenAPI document](https://skmtc.dev/tessl/apis/tessl-api/revisions/7386f1e6295b?raw)