---
title: "Promote an unnamed environment"
method: POST
path: "/projects/{projectId}/environments/{environmentId}/name"
tags: ["Environments"]
---

# Promote an unnamed environment

`POST /projects/{projectId}/environments/{environmentId}/name`

Give an UNNAMED (ad-hoc) environment a name, promoting it IN PLACE — the same environment, now a permanent entry in the project's list, with the same id every existing run still points at.

The ONLY promotion path. `PATCH /environments/{environmentId}` renames an already-named environment and is admin-gated; this is member-gated and refuses a row that already has a name (`409`). The platform keeps them apart on purpose: routing promotion through the rename would either open it to members or leave ad-hoc rows unnameable.

Promotion also drops the content fingerprint, because a named environment is mutable: keeping it would let a later identical composition deduplicate onto a row that has since been edited into something else.

## Path parameters

- `projectId` string, required
- `environmentId` string, required

## Request body

- EnvironmentNameRequest
  - `expectedRevision` integer, required — The revision you last read. Stale ⇒ `409`.
  - `name` string, required — Must be unique among the project's live environments.
  - `description` string

## Response `200`

The promoted environment.

- ProjectEnvironment — A project environment: a named, live-editable execution bundle that eval suites and journeys run against.
  - `id` string, required
  - `projectId` string, required
  - `name` string, required — Unique among the project's live (non-archived) environments.
  - `description` string
  - `hostId` string, required — The host this environment runs against.
  - `serverAttachmentId` string — Present only when the environment pins a standalone server group; otherwise the host config's own servers apply.
  - `modelId` string — The environment's model override. ABSENT means the environment INHERITS the model pinned on its host — not that it has no model. Resolve the environment and read `effectiveModelId` to learn what will actually run.
  - `skillSelection` EnvironmentSkillSelection — An explicit pinned skill selection. Cannot be empty — clear the field instead (send `null` on update) to mean "no pinned skills".
    - `mode` 'explicit', required
    - `skillIds` string[], required — Project-shared skill IDs. Skills carrying supporting files or extra frontmatter, and plugin-component skills, cannot be pinned.
  - `pluginVersionIds` string[] — Pinned plugin VERSION IDs. Narrow by design: the plugin must be installed and enabled, the version must be `ready`, at most one version per plugin may be pinned, and none of its skills may carry supporting files. Not a general-purpose plugin list.
  - `sandboxImageId` string — Sandbox-image pin: a project-shared image (see the images endpoints) that eval runs in this environment boot a fresh sandbox from. Absent when unpinned.
  - `revision` integer, required — Optimistic-concurrency counter. Pass this back as `expectedRevision` on the next write; if it no longer matches, the write is rejected with 409 instead of overwriting a concurrent edit.
  - `archived` boolean, required — Archived environments cannot be edited or launched until restored.
  - `archivedAt` number — Unix epoch milliseconds. Present only when archived.
  - `createdAt` number, required — Unix epoch milliseconds.
  - `updatedAt` number, required — Unix epoch milliseconds.

## Other responses

- `400` — Malformed body or parameters.
- `401` — Missing, invalid, revoked, or orphaned key (`UNAUTHORIZED`) — or the **target MCP server** needs an OAuth grant (`OAUTH_REQUIRED`), which is a property of the server, not your key.
- `403` — Key is valid but not allowed to do this.
- `404` — Unknown project, server, or resource.
- `409` — The resource is not in a state that accepts this write — a stale `expectedRevision`, a duplicate name, or an environment that cannot currently be launched. The request was well-formed; re-read the resource and retry.
- `500` — Something failed on MCPJam's side.
- `502` — Could not connect to the target MCP server.

---

[API](https://skmtc.net/mcpjam/apis/mcpjam-api.md) · [All operations](https://skmtc.net/mcpjam/apis/mcpjam-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mcpjam/mcpjam-api/revisions/8bf151c2dd8b/schema)