Skip to content

CreateSession ​

Type: object additionalProperties: false

FieldRequiredTypeDescription and constraints
allow_multiple_runsNobooleanImmutable session policy. If false, only the run created with the session is allowed and its sandbox is deleted after completion, failure or cancellation. If true, the sandbox is paused for subsequent runs until its retention period expires. Recovery and messages within the current run are allowed in either mode. default: false
namespaceNostringLogical integration or workflow name. Opaque identifier, 1–128 UTF-8 bytes; no NUL or whitespace-only value. Compared exactly, without normalization. minLength: 1
maxLength: 128
external_keyNostringSource-qualified external object key; not unique across sessions. Opaque identifier, 1–512 UTF-8 bytes; no NUL or whitespace-only value. Compared exactly, without normalization. minLength: 1
maxLength: 512
input_fingerprintNostringOpaque input snapshot version for the first run; does not deduplicate requests. Opaque identifier, 1–256 UTF-8 bytes; no NUL or whitespace-only value. Compared exactly, without normalization. minLength: 1
maxLength: 256
configurationYesConfigurationInput
messagesYesarray<TextMessage>Ordered user messages accepted atomically. The last starts the run; earlier messages are injected into the agent context first. minItems: 1
maxItems: 256
envNoobjectExplicit environment variables for the first run's before_run and after_run hooks only. Override session sources with the same names; never passed to the harness, after_create, or before_remove. additionalProperties: {"type":"string"}
servicesNoServiceCodesServices available only to this run's before_run and after_run hooks, as with run env_from. Never passed to the harness, after_create, or before_remove.
env_fromNoarray<string>Allowlisted orchestrator environment variable names for the first run's before_run and after_run hooks only. Resolved before each hook; override session sources and are never passed to the harness, after_create, or before_remove.

JSON Schema ​

json
{
  "additionalProperties": false,
  "properties": {
    "allow_multiple_runs": {
      "description": "Immutable session policy. If false, only the run created with the session is allowed and its sandbox is deleted after completion, failure or cancellation. If true, the sandbox is paused for subsequent runs until its retention period expires. Recovery and messages within the current run are allowed in either mode.",
      "type": "boolean",
      "default": false
    },
    "namespace": {
      "description": "Logical integration or workflow name. Opaque identifier, 1–128 UTF-8 bytes; no NUL or whitespace-only value. Compared exactly, without normalization.",
      "type": "string",
      "minLength": 1,
      "maxLength": 128
    },
    "external_key": {
      "description": "Source-qualified external object key; not unique across sessions. Opaque identifier, 1–512 UTF-8 bytes; no NUL or whitespace-only value. Compared exactly, without normalization.",
      "type": "string",
      "minLength": 1,
      "maxLength": 512
    },
    "input_fingerprint": {
      "description": "Opaque input snapshot version for the first run; does not deduplicate requests. Opaque identifier, 1–256 UTF-8 bytes; no NUL or whitespace-only value. Compared exactly, without normalization.",
      "type": "string",
      "minLength": 1,
      "maxLength": 256
    },
    "configuration": {
      "$ref": "#/components/schemas/ConfigurationInput"
    },
    "messages": {
      "description": "Ordered user messages accepted atomically. The last starts the run; earlier messages are injected into the agent context first.",
      "type": "array",
      "minItems": 1,
      "maxItems": 256,
      "items": {
        "$ref": "#/components/schemas/TextMessage"
      }
    },
    "env": {
      "description": "Explicit environment variables for the first run's before_run and after_run hooks only. Override session sources with the same names; never passed to the harness, after_create, or before_remove.",
      "type": "object",
      "additionalProperties": {
        "type": "string"
      }
    },
    "services": {
      "description": "Services available only to this run's before_run and after_run hooks, as with run env_from. Never passed to the harness, after_create, or before_remove.",
      "$ref": "#/components/schemas/ServiceCodes"
    },
    "env_from": {
      "description": "Allowlisted orchestrator environment variable names for the first run's before_run and after_run hooks only. Resolved before each hook; override session sources and are never passed to the harness, after_create, or before_remove.",
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "configuration",
    "messages"
  ],
  "title": "CreateSession",
  "type": "object"
}

All schemas · HTTP API