Environments

Promote an unnamed environment

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.

POST

projects

{projectId}

environments

{environmentId}

name

Promote an unnamed environment

curl --request POST \
  --url https://app.mcpjam.com/api/v1/projects/{projectId}/environments/{environmentId}/name \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "expectedRevision": 1,
  "name": "Claude Code smoke"
}
'

import requests

url = "https://app.mcpjam.com/api/v1/projects/{projectId}/environments/{environmentId}/name"

payload = {
    "expectedRevision": 1,
    "name": "Claude Code smoke"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({expectedRevision: 1, name: 'Claude Code smoke'})
};

fetch('https://app.mcpjam.com/api/v1/projects/{projectId}/environments/{environmentId}/name', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.mcpjam.com/api/v1/projects/{projectId}/environments/{environmentId}/name",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'expectedRevision' => 1,
    'name' => 'Claude Code smoke'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.mcpjam.com/api/v1/projects/{projectId}/environments/{environmentId}/name"

	payload := strings.NewReader("{\n  \"expectedRevision\": 1,\n  \"name\": \"Claude Code smoke\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://app.mcpjam.com/api/v1/projects/{projectId}/environments/{environmentId}/name")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"expectedRevision\": 1,\n  \"name\": \"Claude Code smoke\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.mcpjam.com/api/v1/projects/{projectId}/environments/{environmentId}/name")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"expectedRevision\": 1,\n  \"name\": \"Claude Code smoke\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "projectId": "<string>",
  "name": "<string>",
  "hostId": "<string>",
  "revision": 123,
  "archived": true,
  "createdAt": 123,
  "updatedAt": 123,
  "description": "<string>",
  "serverAttachmentId": "<string>",
  "modelId": "<string>",
  "skillSelection": {
    "mode": "explicit",
    "skillIds": [
      "<string>"
    ]
  },
  "pluginVersionIds": [
    "<string>"
  ],
  "sandboxImageId": "<string>",
  "archivedAt": 123
}

Authorizations

Authorization

string

header

required

MCPJam API key (sk_…). Create one at Settings → API keys. Guest sessions cannot use the API, and API keys cannot manage other API keys.

Path Parameters

projectId

string

required

ID of the hosted project that contains the server.

environmentId

string

required

Project environment ID, as returned by the project's environment list.

Body

application/json

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

The promoted environment.

A project environment: a named, live-editable execution bundle that eval suites and journeys run against.

string

required

projectId

string

required

name

string

required

Unique among the project's live (non-archived) environments.

hostId

string

required

The host this environment runs against.

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.

createdAt

number

required

Unix epoch milliseconds.

updatedAt

number

required

Unix epoch milliseconds.

description

string

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

object

An explicit pinned skill selection. Cannot be empty — clear the field instead (send null on update) to mean "no pinned skills".

Show child attributes

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.

Minimum string length: 1

Pattern: .*\S.*

archivedAt

number

Unix epoch milliseconds. Present only when archived.

⌘I

Promote an unnamed environment

curl --request POST \
  --url https://app.mcpjam.com/api/v1/projects/{projectId}/environments/{environmentId}/name \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "expectedRevision": 1,
  "name": "Claude Code smoke"
}
'

import requests

url = "https://app.mcpjam.com/api/v1/projects/{projectId}/environments/{environmentId}/name"

payload = {
    "expectedRevision": 1,
    "name": "Claude Code smoke"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({expectedRevision: 1, name: 'Claude Code smoke'})
};

fetch('https://app.mcpjam.com/api/v1/projects/{projectId}/environments/{environmentId}/name', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.mcpjam.com/api/v1/projects/{projectId}/environments/{environmentId}/name",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'expectedRevision' => 1,
    'name' => 'Claude Code smoke'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.mcpjam.com/api/v1/projects/{projectId}/environments/{environmentId}/name"

	payload := strings.NewReader("{\n  \"expectedRevision\": 1,\n  \"name\": \"Claude Code smoke\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://app.mcpjam.com/api/v1/projects/{projectId}/environments/{environmentId}/name")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"expectedRevision\": 1,\n  \"name\": \"Claude Code smoke\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.mcpjam.com/api/v1/projects/{projectId}/environments/{environmentId}/name")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"expectedRevision\": 1,\n  \"name\": \"Claude Code smoke\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "projectId": "<string>",
  "name": "<string>",
  "hostId": "<string>",
  "revision": 123,
  "archived": true,
  "createdAt": 123,
  "updatedAt": 123,
  "description": "<string>",
  "serverAttachmentId": "<string>",
  "modelId": "<string>",
  "skillSelection": {
    "mode": "explicit",
    "skillIds": [
      "<string>"
    ]
  },
  "pluginVersionIds": [
    "<string>"
  ],
  "sandboxImageId": "<string>",
  "archivedAt": 123
}

API Guides

Endpoints

Promote an unnamed environment

Authorizations

Path Parameters

Body

Response