Environments
Update an environment
Rename, set as default, and/or edit flags and contents. Any flag or content change mints a new immutable version; existing sandboxes stay on their pinned version until you call upgrade.
PUT
/
environments
/
{environmentId}
Update a sandbox environment
curl --request PUT \
--url https://boat.dev/api/v1/environments/{environmentId} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "<string>",
"isDefault": true,
"safeForThirdParties": true,
"passGithub": true,
"passSecrets": true,
"passSandboxCredentials": true,
"passAgentsCredentials": true,
"credentialProfileId": "<string>",
"proxyAiCredentials": true,
"envContents": "<string>",
"secretFiles": [
{
"path": ".config/service-account.json",
"contents": "<string>"
}
],
"repositories": [
{
"repositoryId": "<string>",
"baseBranch": "main",
"setupScript": "<string>",
"setupBlocking": true
}
]
}
'import requests
url = "https://boat.dev/api/v1/environments/{environmentId}"
payload = {
"name": "<string>",
"isDefault": True,
"safeForThirdParties": True,
"passGithub": True,
"passSecrets": True,
"passSandboxCredentials": True,
"passAgentsCredentials": True,
"credentialProfileId": "<string>",
"proxyAiCredentials": True,
"envContents": "<string>",
"secretFiles": [
{
"path": ".config/service-account.json",
"contents": "<string>"
}
],
"repositories": [
{
"repositoryId": "<string>",
"baseBranch": "main",
"setupScript": "<string>",
"setupBlocking": True
}
]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PUT',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: '<string>',
isDefault: true,
safeForThirdParties: true,
passGithub: true,
passSecrets: true,
passSandboxCredentials: true,
passAgentsCredentials: true,
credentialProfileId: '<string>',
proxyAiCredentials: true,
envContents: '<string>',
secretFiles: [{path: '.config/service-account.json', contents: '<string>'}],
repositories: [
{
repositoryId: '<string>',
baseBranch: 'main',
setupScript: '<string>',
setupBlocking: true
}
]
})
};
fetch('https://boat.dev/api/v1/environments/{environmentId}', 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://boat.dev/api/v1/environments/{environmentId}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => json_encode([
'name' => '<string>',
'isDefault' => true,
'safeForThirdParties' => true,
'passGithub' => true,
'passSecrets' => true,
'passSandboxCredentials' => true,
'passAgentsCredentials' => true,
'credentialProfileId' => '<string>',
'proxyAiCredentials' => true,
'envContents' => '<string>',
'secretFiles' => [
[
'path' => '.config/service-account.json',
'contents' => '<string>'
]
],
'repositories' => [
[
'repositoryId' => '<string>',
'baseBranch' => 'main',
'setupScript' => '<string>',
'setupBlocking' => true
]
]
]),
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://boat.dev/api/v1/environments/{environmentId}"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"isDefault\": true,\n \"safeForThirdParties\": true,\n \"passGithub\": true,\n \"passSecrets\": true,\n \"passSandboxCredentials\": true,\n \"passAgentsCredentials\": true,\n \"credentialProfileId\": \"<string>\",\n \"proxyAiCredentials\": true,\n \"envContents\": \"<string>\",\n \"secretFiles\": [\n {\n \"path\": \".config/service-account.json\",\n \"contents\": \"<string>\"\n }\n ],\n \"repositories\": [\n {\n \"repositoryId\": \"<string>\",\n \"baseBranch\": \"main\",\n \"setupScript\": \"<string>\",\n \"setupBlocking\": true\n }\n ]\n}")
req, _ := http.NewRequest("PUT", 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.put("https://boat.dev/api/v1/environments/{environmentId}")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\",\n \"isDefault\": true,\n \"safeForThirdParties\": true,\n \"passGithub\": true,\n \"passSecrets\": true,\n \"passSandboxCredentials\": true,\n \"passAgentsCredentials\": true,\n \"credentialProfileId\": \"<string>\",\n \"proxyAiCredentials\": true,\n \"envContents\": \"<string>\",\n \"secretFiles\": [\n {\n \"path\": \".config/service-account.json\",\n \"contents\": \"<string>\"\n }\n ],\n \"repositories\": [\n {\n \"repositoryId\": \"<string>\",\n \"baseBranch\": \"main\",\n \"setupScript\": \"<string>\",\n \"setupBlocking\": true\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://boat.dev/api/v1/environments/{environmentId}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"<string>\",\n \"isDefault\": true,\n \"safeForThirdParties\": true,\n \"passGithub\": true,\n \"passSecrets\": true,\n \"passSandboxCredentials\": true,\n \"passAgentsCredentials\": true,\n \"credentialProfileId\": \"<string>\",\n \"proxyAiCredentials\": true,\n \"envContents\": \"<string>\",\n \"secretFiles\": [\n {\n \"path\": \".config/service-account.json\",\n \"contents\": \"<string>\"\n }\n ],\n \"repositories\": [\n {\n \"repositoryId\": \"<string>\",\n \"baseBranch\": \"main\",\n \"setupScript\": \"<string>\",\n \"setupBlocking\": true\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"environment": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "base",
"isDefault": true,
"latestVersionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"safeForThirdParties": true,
"passGithub": true,
"passSecrets": true,
"passSandboxCredentials": true,
"passAgentsCredentials": true,
"envContents": "<string>",
"secretFiles": [
{
"path": ".config/service-account.json",
"contents": "<string>"
}
],
"versions": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"versionNumber": 123,
"sandboxCount": 123,
"createdAt": "2023-11-07T05:31:56Z"
}
],
"latestVersionNumber": 3,
"safetyAnsweredAt": "2023-11-07T05:31:56Z",
"credentialProfileId": "<string>",
"proxyAiCredentials": true,
"access": {
"restricted": true,
"members": [
"<string>"
]
},
"selectedRepositories": [
{
"id": 123,
"databaseId": "<string>",
"name": "<string>",
"fullName": "acme/web",
"description": "<string>",
"url": "https://github.com/acme/web",
"private": true,
"permissions": "<string>",
"pushedAt": "2023-11-07T05:31:56Z",
"lastUserCommitAt": "2023-11-07T05:31:56Z",
"baseBranch": "main",
"setupRoutineId": "<string>",
"setupScript": "<string>",
"setupBlocking": true
}
]
}
}{
"ok": false,
"type": "sandbox.error",
"status": 400,
"code": "invalid_json",
"message": "Request body must be valid JSON.",
"error": {
"code": "invalid_json",
"message": "Request body must be valid JSON.",
"status": 400
},
"requestId": "req_01HX..."
}{
"ok": false,
"type": "sandbox.error",
"status": 401,
"code": "unauthorized",
"message": "Unauthorized",
"error": {
"code": "unauthorized",
"message": "Unauthorized",
"status": 401
},
"requestId": "req_01HX..."
}{
"ok": false,
"type": "sandbox.error",
"status": 409,
"code": "provider_not_configured",
"message": "Prompting is locked until Codex is configured on the Agents page.",
"requestId": "req_01HX...",
"error": {
"code": "<string>",
"message": "<string>",
"status": 123,
"details": {}
}
}Authorizations
Boat bearer token in the form boat_.... Service API keys authenticate sandbox operations.
Path Parameters
Environment id returned by GET /environments.
Query Parameters
Billing wallet for this request: an organization you belong to, by id (team_…) or by name as GET /orgs lists it (case-insensitive), or personal. Omitted, the account's active wallet applies (PATCH /orgs/active; personal until set). Two organizations sharing the name answer 409 ambiguous_org and need the id. Sandboxes and snapshots stay creator-private. On /environments routes, only this query parameter selects the organization's shared environments; the X-Boat-Org header and the active wallet do not apply there. Members read them, owners and admins change them.
Body
application/json
Rename, set-default, and/or edit flags and contents. Any flag or content change mints a new immutable version; existing sandboxes are not touched until you call upgrade.
New environment name.
Set to true to make this the default environment (clears the flag on the previous default).
Id or name of a credential profile you can use, or null for the sandbox owner's default profile. Unknown profiles return 404 credential_profile_not_found.
With safeForThirdParties true, pass AI credentials as proxy placeholders. Setting true needs the AI credentials proxy on for the profile owner, else 400 ai_proxy_off.
Set who can use an organization environment (owner or admin) or profile (owner). A change does not touch running sandboxes. A bad list returns 400 invalid_access.
Show child attributes
Show child attributes
Full .env-style content for the new version.
Show child attributes
Show child attributes
Full replacement of the version's repository selection. Each item selects one repository by its internal databaseId (from GET /repos).
Show child attributes
Show child attributes
⌘I
Update a sandbox environment
curl --request PUT \
--url https://boat.dev/api/v1/environments/{environmentId} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "<string>",
"isDefault": true,
"safeForThirdParties": true,
"passGithub": true,
"passSecrets": true,
"passSandboxCredentials": true,
"passAgentsCredentials": true,
"credentialProfileId": "<string>",
"proxyAiCredentials": true,
"envContents": "<string>",
"secretFiles": [
{
"path": ".config/service-account.json",
"contents": "<string>"
}
],
"repositories": [
{
"repositoryId": "<string>",
"baseBranch": "main",
"setupScript": "<string>",
"setupBlocking": true
}
]
}
'import requests
url = "https://boat.dev/api/v1/environments/{environmentId}"
payload = {
"name": "<string>",
"isDefault": True,
"safeForThirdParties": True,
"passGithub": True,
"passSecrets": True,
"passSandboxCredentials": True,
"passAgentsCredentials": True,
"credentialProfileId": "<string>",
"proxyAiCredentials": True,
"envContents": "<string>",
"secretFiles": [
{
"path": ".config/service-account.json",
"contents": "<string>"
}
],
"repositories": [
{
"repositoryId": "<string>",
"baseBranch": "main",
"setupScript": "<string>",
"setupBlocking": True
}
]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PUT',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: '<string>',
isDefault: true,
safeForThirdParties: true,
passGithub: true,
passSecrets: true,
passSandboxCredentials: true,
passAgentsCredentials: true,
credentialProfileId: '<string>',
proxyAiCredentials: true,
envContents: '<string>',
secretFiles: [{path: '.config/service-account.json', contents: '<string>'}],
repositories: [
{
repositoryId: '<string>',
baseBranch: 'main',
setupScript: '<string>',
setupBlocking: true
}
]
})
};
fetch('https://boat.dev/api/v1/environments/{environmentId}', 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://boat.dev/api/v1/environments/{environmentId}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => json_encode([
'name' => '<string>',
'isDefault' => true,
'safeForThirdParties' => true,
'passGithub' => true,
'passSecrets' => true,
'passSandboxCredentials' => true,
'passAgentsCredentials' => true,
'credentialProfileId' => '<string>',
'proxyAiCredentials' => true,
'envContents' => '<string>',
'secretFiles' => [
[
'path' => '.config/service-account.json',
'contents' => '<string>'
]
],
'repositories' => [
[
'repositoryId' => '<string>',
'baseBranch' => 'main',
'setupScript' => '<string>',
'setupBlocking' => true
]
]
]),
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://boat.dev/api/v1/environments/{environmentId}"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"isDefault\": true,\n \"safeForThirdParties\": true,\n \"passGithub\": true,\n \"passSecrets\": true,\n \"passSandboxCredentials\": true,\n \"passAgentsCredentials\": true,\n \"credentialProfileId\": \"<string>\",\n \"proxyAiCredentials\": true,\n \"envContents\": \"<string>\",\n \"secretFiles\": [\n {\n \"path\": \".config/service-account.json\",\n \"contents\": \"<string>\"\n }\n ],\n \"repositories\": [\n {\n \"repositoryId\": \"<string>\",\n \"baseBranch\": \"main\",\n \"setupScript\": \"<string>\",\n \"setupBlocking\": true\n }\n ]\n}")
req, _ := http.NewRequest("PUT", 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.put("https://boat.dev/api/v1/environments/{environmentId}")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\",\n \"isDefault\": true,\n \"safeForThirdParties\": true,\n \"passGithub\": true,\n \"passSecrets\": true,\n \"passSandboxCredentials\": true,\n \"passAgentsCredentials\": true,\n \"credentialProfileId\": \"<string>\",\n \"proxyAiCredentials\": true,\n \"envContents\": \"<string>\",\n \"secretFiles\": [\n {\n \"path\": \".config/service-account.json\",\n \"contents\": \"<string>\"\n }\n ],\n \"repositories\": [\n {\n \"repositoryId\": \"<string>\",\n \"baseBranch\": \"main\",\n \"setupScript\": \"<string>\",\n \"setupBlocking\": true\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://boat.dev/api/v1/environments/{environmentId}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"<string>\",\n \"isDefault\": true,\n \"safeForThirdParties\": true,\n \"passGithub\": true,\n \"passSecrets\": true,\n \"passSandboxCredentials\": true,\n \"passAgentsCredentials\": true,\n \"credentialProfileId\": \"<string>\",\n \"proxyAiCredentials\": true,\n \"envContents\": \"<string>\",\n \"secretFiles\": [\n {\n \"path\": \".config/service-account.json\",\n \"contents\": \"<string>\"\n }\n ],\n \"repositories\": [\n {\n \"repositoryId\": \"<string>\",\n \"baseBranch\": \"main\",\n \"setupScript\": \"<string>\",\n \"setupBlocking\": true\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"environment": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "base",
"isDefault": true,
"latestVersionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"safeForThirdParties": true,
"passGithub": true,
"passSecrets": true,
"passSandboxCredentials": true,
"passAgentsCredentials": true,
"envContents": "<string>",
"secretFiles": [
{
"path": ".config/service-account.json",
"contents": "<string>"
}
],
"versions": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"versionNumber": 123,
"sandboxCount": 123,
"createdAt": "2023-11-07T05:31:56Z"
}
],
"latestVersionNumber": 3,
"safetyAnsweredAt": "2023-11-07T05:31:56Z",
"credentialProfileId": "<string>",
"proxyAiCredentials": true,
"access": {
"restricted": true,
"members": [
"<string>"
]
},
"selectedRepositories": [
{
"id": 123,
"databaseId": "<string>",
"name": "<string>",
"fullName": "acme/web",
"description": "<string>",
"url": "https://github.com/acme/web",
"private": true,
"permissions": "<string>",
"pushedAt": "2023-11-07T05:31:56Z",
"lastUserCommitAt": "2023-11-07T05:31:56Z",
"baseBranch": "main",
"setupRoutineId": "<string>",
"setupScript": "<string>",
"setupBlocking": true
}
]
}
}{
"ok": false,
"type": "sandbox.error",
"status": 400,
"code": "invalid_json",
"message": "Request body must be valid JSON.",
"error": {
"code": "invalid_json",
"message": "Request body must be valid JSON.",
"status": 400
},
"requestId": "req_01HX..."
}{
"ok": false,
"type": "sandbox.error",
"status": 401,
"code": "unauthorized",
"message": "Unauthorized",
"error": {
"code": "unauthorized",
"message": "Unauthorized",
"status": 401
},
"requestId": "req_01HX..."
}{
"ok": false,
"type": "sandbox.error",
"status": 409,
"code": "provider_not_configured",
"message": "Prompting is locked until Codex is configured on the Agents page.",
"requestId": "req_01HX...",
"error": {
"code": "<string>",
"message": "<string>",
"status": 123,
"details": {}
}
}