CreateEnvironmentRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/ishlabs-io/json-schema/ishlabs-io-create-environment-request-schema.json",
  "title": "CreateEnvironmentRequest",
  "x-generated": "2026-11-13",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/ishlabs-io-openapi.json#/components/schemas/CreateEnvironmentRequest",
  "additionalProperties": false,
  "properties": {
    "config": {
      "$ref": "#/$defs/EnvironmentConfig"
    },
    "example_actions": {
      "description": "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.",
      "items": {
        "additionalProperties": true,
        "type": "object"
      },
      "title": "Example Actions",
      "type": "array"
    },
    "get_or_create": {
      "default": false,
      "description": "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).",
      "title": "Get Or Create",
      "type": "boolean"
    },
    "kind": {
      "$ref": "#/$defs/EnvironmentKind",
      "description": "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."
    },
    "name": {
      "maxLength": 120,
      "minLength": 1,
      "title": "Name",
      "type": "string"
    },
    "observation_retention": {
      "anyOf": [
        {
          "$ref": "#/$defs/ObservationRetention"
        },
        {
          "type": "null"
        }
      ],
      "description": "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."
    },
    "operating_notes": {
      "anyOf": [
        {
          "maxLength": 8000,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "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.",
      "title": "Operating Notes"
    },
    "slug": {
      "anyOf": [
        {
          "maxLength": 120,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Slug"
    }
  },
  "required": [
    "name",
    "kind"
  ],
  "type": "object",
  "$defs": {
    "EnvironmentConfig": {
      "additionalProperties": false,
      "description": "The per-kind configuration of an environment.\n\nEvery 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.",
      "properties": {
        "app_artifact": {
          "anyOf": [
            {
              "maxLength": 2000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "App Artifact"
        },
        "origins": {
          "anyOf": [
            {
              "items": {
                "type": "string"
              },
              "maxItems": 50,
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "title": "Origins"
        },
        "url": {
          "anyOf": [
            {
              "maxLength": 2000,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Url"
        }
      },
      "title": "EnvironmentConfig",
      "type": "object"
    },
    "EnvironmentKind": {
      "description": "What kind of surface a registered environment is.\n\nDeliberately not called `platform`: `kind` is the one vocabulary the environment object owns, and it stays stable no matter what the thing you are testing calls itself.\n\nClosed on write (an unknown kind is a 422) and OPEN on read: new kinds are added over time, so a client must tolerate a value it does not recognize rather than failing on it.",
      "enum": [
        "web",
        "device",
        "world"
      ],
      "title": "EnvironmentKind",
      "type": "string"
    },
    "ObservationRetention": {
      "description": "How long a session's observation frames are kept: `none` (discarded after the turn), `30d`, `90d`, or `indefinite`.\n\nOne field rather than a flag beside a window, so the incoherent pair (off, 90 days) cannot be expressed. Resolved once when the session opens, from the session's own value or the registered environment's default, and fixed for that session's lifetime: editing the environment later never changes what an open session promised.\n\nOpen union: new windows may be added over time; clients must tolerate unknown values rather than failing on them.",
      "enum": [
        "none",
        "30d",
        "90d",
        "indefinite"
      ],
      "title": "ObservationRetention",
      "type": "string"
    }
  }
}