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

# POST /v1/orgs/{orgId}/environments

`POST /v1/orgs/{orgId}/environments`

## Request

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

Creates a named environment held by the organization. The supplied `.env` payload is validated, sealed under the organization key, and never returned by any read path. The environment is usable by no project until it is bound to one.

## Path parameters

- `orgId` string, uuid, required

## Headers

- `Authorization` string

## Request body

- object
  - `name` string, required
  - `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`.
  - `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 `201`

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`: 2 info
  - added the new optional request property `metadata/mcpServerNames`
  - added the required property `data/attributes/secretRefs` to the response with the `201` 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 `201`
  - added the new `agent-retro` enum value to the `data/attributes/metadata/anyOf[subschema #1]/improveDevelopmentLoop` response property for the response status `201`
  - removed `subschema #1, subschema #2` from the `data/attributes/metadata/anyOf[subschema #1]/improveDevelopmentLoop` response property `anyOf` list for the response status `201`
- **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 `201`
- …earlier changes not shown

[Operation history](https://skmtc.dev/tessl/apis/tessl-api/changes/v1/orgs/:orgId/environments/post.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)