curl --request POST \
--url https://api.ishlabs.io/api/v1/workspaces/{workspace_id}/environments \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"config": {
"url": "https://staging.example.com/checkout"
},
"example_actions": [
{
"description": "Move from the cart to the payment step.",
"name": "continue_to_payment"
},
{
"description": "Return to the cart without paying.",
"name": "back_to_cart"
}
],
"kind": "web",
"name": "Checkout (staging)",
"operating_notes": "Test card 4242 4242 4242 4242. Coupon codes are disabled here."
}
'import requests
url = "https://api.ishlabs.io/api/v1/workspaces/{workspace_id}/environments"
payload = {
"config": { "url": "https://staging.example.com/checkout" },
"example_actions": [
{
"description": "Move from the cart to the payment step.",
"name": "continue_to_payment"
},
{
"description": "Return to the cart without paying.",
"name": "back_to_cart"
}
],
"kind": "web",
"name": "Checkout (staging)",
"operating_notes": "Test card 4242 4242 4242 4242. Coupon codes are disabled here."
}
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({
config: {url: 'https://staging.example.com/checkout'},
example_actions: [
{
description: 'Move from the cart to the payment step.',
name: 'continue_to_payment'
},
{description: 'Return to the cart without paying.', name: 'back_to_cart'}
],
kind: 'web',
name: 'Checkout (staging)',
operating_notes: 'Test card 4242 4242 4242 4242. Coupon codes are disabled here.'
})
};
fetch('https://api.ishlabs.io/api/v1/workspaces/{workspace_id}/environments', 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://api.ishlabs.io/api/v1/workspaces/{workspace_id}/environments",
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([
'config' => [
'url' => 'https://staging.example.com/checkout'
],
'example_actions' => [
[
'description' => 'Move from the cart to the payment step.',
'name' => 'continue_to_payment'
],
[
'description' => 'Return to the cart without paying.',
'name' => 'back_to_cart'
]
],
'kind' => 'web',
'name' => 'Checkout (staging)',
'operating_notes' => 'Test card 4242 4242 4242 4242. Coupon codes are disabled here.'
]),
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://api.ishlabs.io/api/v1/workspaces/{workspace_id}/environments"
payload := strings.NewReader("{\n \"config\": {\n \"url\": \"https://staging.example.com/checkout\"\n },\n \"example_actions\": [\n {\n \"description\": \"Move from the cart to the payment step.\",\n \"name\": \"continue_to_payment\"\n },\n {\n \"description\": \"Return to the cart without paying.\",\n \"name\": \"back_to_cart\"\n }\n ],\n \"kind\": \"web\",\n \"name\": \"Checkout (staging)\",\n \"operating_notes\": \"Test card 4242 4242 4242 4242. Coupon codes are disabled here.\"\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://api.ishlabs.io/api/v1/workspaces/{workspace_id}/environments")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"config\": {\n \"url\": \"https://staging.example.com/checkout\"\n },\n \"example_actions\": [\n {\n \"description\": \"Move from the cart to the payment step.\",\n \"name\": \"continue_to_payment\"\n },\n {\n \"description\": \"Return to the cart without paying.\",\n \"name\": \"back_to_cart\"\n }\n ],\n \"kind\": \"web\",\n \"name\": \"Checkout (staging)\",\n \"operating_notes\": \"Test card 4242 4242 4242 4242. Coupon codes are disabled here.\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.ishlabs.io/api/v1/workspaces/{workspace_id}/environments")
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 \"config\": {\n \"url\": \"https://staging.example.com/checkout\"\n },\n \"example_actions\": [\n {\n \"description\": \"Move from the cart to the payment step.\",\n \"name\": \"continue_to_payment\"\n },\n {\n \"description\": \"Return to the cart without paying.\",\n \"name\": \"back_to_cart\"\n }\n ],\n \"kind\": \"web\",\n \"name\": \"Checkout (staging)\",\n \"operating_notes\": \"Test card 4242 4242 4242 4242. Coupon codes are disabled here.\"\n}"
response = http.request(request)
puts response.read_body{
"address": "<string>",
"archived_at": "2023-11-07T05:31:56Z",
"config": {
"app_artifact": "<string>",
"origins": [
"<string>"
],
"url": "<string>"
},
"created_at": "2023-11-07T05:31:56Z",
"example_actions": [
{}
],
"hosting": "<string>",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"kind": "<string>",
"name": "<string>",
"observation_retention": "<string>",
"operating_notes": "<string>",
"revision": 123,
"slug": "<string>",
"updated_at": "2023-11-07T05:31:56Z",
"workspace_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}{
"address": "<string>",
"archived_at": "2023-11-07T05:31:56Z",
"config": {
"app_artifact": "<string>",
"origins": [
"<string>"
],
"url": "<string>"
},
"created_at": "2023-11-07T05:31:56Z",
"example_actions": [
{}
],
"hosting": "<string>",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"kind": "<string>",
"name": "<string>",
"observation_retention": "<string>",
"operating_notes": "<string>",
"revision": 123,
"slug": "<string>",
"updated_at": "2023-11-07T05:31:56Z",
"workspace_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}{
"detail": "<string>",
"request_id": "<string>",
"docs_url": "<string>"
}{
"detail": "<string>",
"request_id": "<string>",
"docs_url": "<string>"
}{
"detail": "<string>",
"request_id": "<string>",
"docs_url": "<string>"
}{
"detail": "<string>",
"request_id": "<string>",
"docs_url": "<string>"
}{
"detail": "<string>",
"error": "<string>",
"error_code": "<string>",
"errors": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"allowed_values": [
"<unknown>"
],
"input": "<string>"
}
],
"retryable": true,
"status": 123,
"suggestions": [
"<string>"
]
}{
"detail": "<string>",
"request_id": "<string>",
"docs_url": "<string>"
}Create Environment
Register an environment: a named target sessions can be opened against.
Supports the standard Idempotency-Key header, which is the mechanism to
reach for in CI: a retry with the same key and body replays the original
environment (200 instead of 201), and the same key with a different body is a
409 idempotency_conflict.
get_or_create is the older, coarser flag and remains supported. Note what
it does NOT do: on a name match it returns the EXISTING row untouched and
IGNORES every other field on this request, so a request whose config has
drifted from the stored one succeeds while changing nothing. Use
Idempotency-Key for retry safety and PATCH to reconcile config.
curl --request POST \
--url https://api.ishlabs.io/api/v1/workspaces/{workspace_id}/environments \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"config": {
"url": "https://staging.example.com/checkout"
},
"example_actions": [
{
"description": "Move from the cart to the payment step.",
"name": "continue_to_payment"
},
{
"description": "Return to the cart without paying.",
"name": "back_to_cart"
}
],
"kind": "web",
"name": "Checkout (staging)",
"operating_notes": "Test card 4242 4242 4242 4242. Coupon codes are disabled here."
}
'import requests
url = "https://api.ishlabs.io/api/v1/workspaces/{workspace_id}/environments"
payload = {
"config": { "url": "https://staging.example.com/checkout" },
"example_actions": [
{
"description": "Move from the cart to the payment step.",
"name": "continue_to_payment"
},
{
"description": "Return to the cart without paying.",
"name": "back_to_cart"
}
],
"kind": "web",
"name": "Checkout (staging)",
"operating_notes": "Test card 4242 4242 4242 4242. Coupon codes are disabled here."
}
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({
config: {url: 'https://staging.example.com/checkout'},
example_actions: [
{
description: 'Move from the cart to the payment step.',
name: 'continue_to_payment'
},
{description: 'Return to the cart without paying.', name: 'back_to_cart'}
],
kind: 'web',
name: 'Checkout (staging)',
operating_notes: 'Test card 4242 4242 4242 4242. Coupon codes are disabled here.'
})
};
fetch('https://api.ishlabs.io/api/v1/workspaces/{workspace_id}/environments', 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://api.ishlabs.io/api/v1/workspaces/{workspace_id}/environments",
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([
'config' => [
'url' => 'https://staging.example.com/checkout'
],
'example_actions' => [
[
'description' => 'Move from the cart to the payment step.',
'name' => 'continue_to_payment'
],
[
'description' => 'Return to the cart without paying.',
'name' => 'back_to_cart'
]
],
'kind' => 'web',
'name' => 'Checkout (staging)',
'operating_notes' => 'Test card 4242 4242 4242 4242. Coupon codes are disabled here.'
]),
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://api.ishlabs.io/api/v1/workspaces/{workspace_id}/environments"
payload := strings.NewReader("{\n \"config\": {\n \"url\": \"https://staging.example.com/checkout\"\n },\n \"example_actions\": [\n {\n \"description\": \"Move from the cart to the payment step.\",\n \"name\": \"continue_to_payment\"\n },\n {\n \"description\": \"Return to the cart without paying.\",\n \"name\": \"back_to_cart\"\n }\n ],\n \"kind\": \"web\",\n \"name\": \"Checkout (staging)\",\n \"operating_notes\": \"Test card 4242 4242 4242 4242. Coupon codes are disabled here.\"\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://api.ishlabs.io/api/v1/workspaces/{workspace_id}/environments")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"config\": {\n \"url\": \"https://staging.example.com/checkout\"\n },\n \"example_actions\": [\n {\n \"description\": \"Move from the cart to the payment step.\",\n \"name\": \"continue_to_payment\"\n },\n {\n \"description\": \"Return to the cart without paying.\",\n \"name\": \"back_to_cart\"\n }\n ],\n \"kind\": \"web\",\n \"name\": \"Checkout (staging)\",\n \"operating_notes\": \"Test card 4242 4242 4242 4242. Coupon codes are disabled here.\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.ishlabs.io/api/v1/workspaces/{workspace_id}/environments")
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 \"config\": {\n \"url\": \"https://staging.example.com/checkout\"\n },\n \"example_actions\": [\n {\n \"description\": \"Move from the cart to the payment step.\",\n \"name\": \"continue_to_payment\"\n },\n {\n \"description\": \"Return to the cart without paying.\",\n \"name\": \"back_to_cart\"\n }\n ],\n \"kind\": \"web\",\n \"name\": \"Checkout (staging)\",\n \"operating_notes\": \"Test card 4242 4242 4242 4242. Coupon codes are disabled here.\"\n}"
response = http.request(request)
puts response.read_body{
"address": "<string>",
"archived_at": "2023-11-07T05:31:56Z",
"config": {
"app_artifact": "<string>",
"origins": [
"<string>"
],
"url": "<string>"
},
"created_at": "2023-11-07T05:31:56Z",
"example_actions": [
{}
],
"hosting": "<string>",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"kind": "<string>",
"name": "<string>",
"observation_retention": "<string>",
"operating_notes": "<string>",
"revision": 123,
"slug": "<string>",
"updated_at": "2023-11-07T05:31:56Z",
"workspace_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}{
"address": "<string>",
"archived_at": "2023-11-07T05:31:56Z",
"config": {
"app_artifact": "<string>",
"origins": [
"<string>"
],
"url": "<string>"
},
"created_at": "2023-11-07T05:31:56Z",
"example_actions": [
{}
],
"hosting": "<string>",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"kind": "<string>",
"name": "<string>",
"observation_retention": "<string>",
"operating_notes": "<string>",
"revision": 123,
"slug": "<string>",
"updated_at": "2023-11-07T05:31:56Z",
"workspace_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}{
"detail": "<string>",
"request_id": "<string>",
"docs_url": "<string>"
}{
"detail": "<string>",
"request_id": "<string>",
"docs_url": "<string>"
}{
"detail": "<string>",
"request_id": "<string>",
"docs_url": "<string>"
}{
"detail": "<string>",
"request_id": "<string>",
"docs_url": "<string>"
}{
"detail": "<string>",
"error": "<string>",
"error_code": "<string>",
"errors": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"allowed_values": [
"<unknown>"
],
"input": "<string>"
}
],
"retryable": true,
"status": 123,
"suggestions": [
"<string>"
]
}{
"detail": "<string>",
"request_id": "<string>",
"docs_url": "<string>"
}Authorizations
Workspace API key as a bearer token: Authorization: Bearer ish_sk_live_.... Keys are workspace-scoped machine principals minted in Settings > Developers (shown once at mint). Scopes: sessions:run (create a session, submit turns, close), sessions:read (read the session and its decision trace), environments:read and environments:write (manage the workspace's registered environments), tasks:read and tasks:write (manage the workspace's registered tasks), people:read and people:write (the people the workspace can run a session for), and usage:read (the workspace's own consumption, spend limits and rate-limit budgets). A key is minted with sessions:run, sessions:read, and tasks:read by default; every other scope must be requested, people:read and usage:read included. An ish user access token also works on the same header for personal scripts.
Headers
Path Parameters
Body
What kind of surface this is. Closed on write, open on read: Open union: new values may be added over time; clients must tolerate unknown values rather than failing on them.
web, device, world 1 - 120The per-kind configuration of an environment.
Every field is optional at the type level and required by KIND at validation time: a web environment needs url, and so on. Unknown keys are REJECTED on write, so a typo surfaces as a 422 instead of a target that was silently never set.
Show child attributes
Show child attributes
Example action vocabulary for this environment (same shape as a turn's valid_actions). NON-AUTHORITATIVE: documentation and SDK scaffolding only, never read at turn time. Every turn declares its own valid_actions, which is the only authoritative source.
Idempotent register for CI: when a LIVE environment with this name (case-insensitive) and the SAME kind already exists, return it with 200 instead of 409. The existing row is returned AS IS: config, notes and example_actions on this request are ignored, never silently applied, and the address-dedupe check is not evaluated on this path (nothing is written). A name held by a different kind still conflicts (409).
How long sessions on this environment keep their observation frames: none (discard after each turn), 30d, 90d, or indefinite. Omit for the default (30d). A session may override this at open; the resolved value is fixed for that session's life.
none, 30d, 90d, indefinite Operating manual for the RESOLVER only, never shown to the person. Becomes the default resolver_guidance for sessions opened against this environment; a session may pass its own, which wins.
8000120Response
The existing environment, RETURNED AS IS: nothing on this request was applied to it. Two paths reach here: an Idempotency-Key replay (same key, same body), or get_or_create with a live environment already holding this name and kind.
A registered environment as the caller sees it.
Normalized target identity derived from config (scheme, host and path only). A duplicate-registration guard, NOT the environment's identity, since sessions always reference the id.
Set when the environment is archived (DELETE). An archived environment stays readable by id so existing sessions keep resolving, is hidden from the default list, and frees its name for reuse.
The configuration of an environment as stored, tolerant of unknown keys.
Same fields as the write shape, but a key this client does not know is IGNORED rather than rejected: reads must keep working across server versions, and because a list response parses the whole page, one unfamiliar key would otherwise fail an entire workspace listing rather than its own row. Closed on write, open on read.
Show child attributes
Show child attributes
Who computes the next observation for this environment. Derived from kind and config, never client-set. Open union: new values may be added over time; clients must tolerate unknown values rather than failing on them.
What kind of surface this is. Open union: new values may be added over time; clients must tolerate unknown values rather than failing on them.
How long sessions on this environment keep their observation frames: none, 30d, 90d, or indefinite. Open union: new values may be added over time; clients must tolerate unknown values rather than failing on them.
Increments on every write to this environment's identity or configuration. Usage is aggregated by (id, revision), so a run reports against the configuration it actually ran on. Archiving does not change it.