Create Environment

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>"
}

API reference

Create Environment

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.

POST

api

workspaces

{workspace_id}

environments

Create Environment

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

Authorization

string

header

required

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

Idempotency-Key

string | null

Path Parameters

workspace_id

string<uuid>

required

Body

application/json

kind

enum<string>

required

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.

Available options:

web,

device,

world

name

string

required

Required string length: 1 - 120

config

EnvironmentConfig · object

The 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

example_actions

Example Actions · object[]

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.

get_or_create

boolean

default:false

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).

observation_retention

enum<string> | null

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.

Available options:

none,

30d,

90d,

indefinite

operating_notes

string | null

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.

Maximum string length: 8000

slug

string | null

Maximum string length: 120

Response

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.

address

string | null

required

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.

archived_at

string<date-time> | null

required

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.

config

StoredEnvironmentConfig · object

required

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

created_at

string<date-time>

required

example_actions

Example Actions · object[]

required

hosting

string

required

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.

string<uuid>

required

kind

string

required

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.

name

string

required

observation_retention

string

required

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.

operating_notes

string | null

required

revision

integer

required

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.

slug

string | null

required

updated_at

string<date-time>

required

workspace_id

string<uuid>

required

Get started

Core concepts

Guides

API reference

Versioning and changes

Create Environment

Authorizations

Headers

Path Parameters

Body

Response