Update Session presentation or execution defaults

PATCH

/v1/sessions/{sessionId}

const url = 'https://example.com/v1/sessions/9f2b7c14-59d3-4f7a-b8e1-2a6c05d4e731';
const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"title":"Rate limit the payments endpoint (PAY-4821)","model":"claude-sonnet-5"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request PATCH \
  --url https://example.com/v1/sessions/9f2b7c14-59d3-4f7a-b8e1-2a6c05d4e731 \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "title": "Rate limit the payments endpoint (PAY-4821)", "model": "claude-sonnet-5" }'

Runtime may change only before the first Turn. Later Turns may select a model but must inherit the settled Session runtime; a supplied runtime is accepted only when it repeats that value for rolling-client compatibility.

Authorizations

cloudInstallationBearer

Parameters

Path Parameters

sessionId

required

A UUID identifying one Cloud resource; Session, Turn, Publication and Merge ids are minted by the caller so an ambiguous retry addresses the same durable command instead of creating a second one.

string format: uuid

Example

9f2b7c14-59d3-4f7a-b8e1-2a6c05d4e731

A UUID you mint and own; it is the idempotency key for creation and the address of every Turn, artifact and publication underneath

Request Body^required

application/json

Mutable Session presentation and execution defaults; send at least one field. It never affects a Run that is already dispatched.

object

>= 1 properties

title

New human-facing Session name

string

>= 1 characters <= 160 characters

model

Model that later Turns default to, chosen from the models the Session’s settled runtime advertises

string

>= 1 characters <= 128 characters

runtime

Accepted only before the first Turn is admitted; afterwards it must equal the settled runtime, and switching runtimes requires a new Session

string

<= 64 characters /^[a-z0-9][a-z0-9-]*$/

Example

{
  "title": "Rate limit the payments endpoint (PAY-4821)",
  "model": "claude-sonnet-5"
}

Responses

200

Updated Session

application/json

Envelope returned by every single-Session read and write.

object

session

required

The Session as it stands after this request; a create that was an idempotent replay returns the already-stored Session unchanged

object

required

The caller-owned Session id, unchanged from the create request

string format: uuid

sessionUrl

required

Canonical first-party browser URL for handing this Session to a human

string format: uri

organizationId

required

Organization that owns the Session; every credential is authorized against this organization

string format: uuid

title

required

Human-facing name — the supplied title, or one derived from task when none was given

string

origin

Correlation metadata supplied at creation; absent when none was sent

object

tenantKey

required

Stable opaque identifier for the external tenant the work belongs to, not its display name

string

>= 1 characters <= 128 characters

objectType

required

The caller’s own kind name for the originating record, such as ticket or issue

string

>= 1 characters <= 64 characters

objectId

required

The caller’s stable opaque id for that record, so a Session can always be traced back to the business object

string

>= 1 characters <= 256 characters

endUserId

Stable one-way hash of the external tenant/user pair; never raw PII.

string

>= 1 characters <= 128 characters

label

Short human-readable name for the originating record, shown when the Session is handed to a person

string

<= 256 characters

url

HTTPS deep link back to the originating record in the caller’s product

string format: uri

/^https:///

source

Repository checked out into the sandbox, with the exact base the Session was pinned to; absent for a Session with no repository

object

One of:

object
object

object

kind

required

Allowed value: public

url

required

string

label

required

string

model

Model in effect for the next Turn; absent when a runtime-managed agent supplies its own default

string

runtime

The settled foreign agent runtime id, such as claude-code or codex; absent means the native WAMP runtime

string

workspace

required

Sandbox attachment — unavailable when no lease is held, attached with the lease expiresAt, expired once that lease has lapsed; losing it does not end the Session

object

state

required

string

Allowed values: unavailable attached expired

expiresAt

string format: date-time

continuation

required

Whether and at what fidelity this Session can be carried into another Run

object

canContinue

required

Whether a new Turn can be admitted for this Session; false only while state is unavailable

boolean

state

required

live while a sandbox lease is still held, fresh before any Run has been accepted, restorable when a sealed checkpoint can be replayed into a new sandbox, unavailable when neither is possible

string

Allowed values: live fresh restorable unavailable

conversation

required

Fidelity the conversation would be restored at — live in an attached sandbox, exact from a full checkpoint, result_only when just prior results survive, none when nothing does

object

fidelity

required

string

Allowed values: live exact result_only none

workspace

required

Fidelity the working tree would be restored at — live, portable_tree from a checkpointed tree, or none

object

fidelity

required

string

Allowed values: live portable_tree none

environment

required

Always current: a restore lands in the currently promoted execution environment, and Cloud never claims it retained a specific image or runtime digest

object

fidelity

required

Allowed value: current

boundaryRunId

The Run whose completion sealed the checkpoint this projection describes; absent when no checkpoint exists

string format: uuid

reason

Why continuation is impossible — checkpoint_unavailable, conversation_not_restorable, or workspace_not_restorable; present only when canContinue is false

string

phase

required

Last execution phase the runner reported (idle, provisioning, running, awaiting, finalizing, completed, failed); advisory presentation state — read the Run for authoritative status

string

createdBy

required

Whether a human user or an App installation created the Session, and that actor’s id; an installation-created Session keeps its App authority even when a human later manages it

object

kind

required

string

Allowed values: user app_installation

required

A UUID identifying one Cloud resource; Session, Turn, Publication and Merge ids are minted by the caller so an ambiguous retry addresses the same durable command instead of creating a second one.

string format: uuid

activeRun

Present only while a Run is queued, dispatching or running — this is the id to cancel

object

required

A UUID identifying one Cloud resource; Session, Turn, Publication and Merge ids are minted by the caller so an ambiguous retry addresses the same durable command instead of creating a second one.

string format: uuid

createdAt

required

When the Session was admitted

string format: date-time

updatedAt

required

Last time durable Session state changed; the Session list is ordered by this value descending

string format: date-time

Example

{
  "session": {
    "id": "9f2b7c14-59d3-4f7a-b8e1-2a6c05d4e731",
    "sessionUrl": "https://cloud.wamp.dev/sessions/9f2b7c14-59d3-4f7a-b8e1-2a6c05d4e731",
    "organizationId": "0b9a6f3e-5c21-4d78-9e64-8f1a2b7c3d05",
    "title": "Rate limit the payments endpoint (PAY-4821)",
    "origin": {
      "tenantKey": "acme",
      "objectType": "issue",
      "objectId": "PAY-4821",
      "endUserId": "9c1f0a7d4b62e35810af2d6c95b7e043",
      "label": "PAY-4821 Rate limit the payments endpoint",
      "url": "https://acme.example.com/issues/PAY-4821"
    },
    "source": {
      "kind": "github",
      "grantId": "74c5a903-8e6f-4b1d-a052-3c9e18d7f64b",
      "label": "acme/checkout-service",
      "private": true,
      "baseBranch": "main",
      "baseOid": "5a3e170c93eda8209e3f5592fe1e1d9976fe26ab"
    },
    "model": "claude-sonnet-5",
    "runtime": "wamp",
    "workspace": {
      "state": "attached",
      "expiresAt": "2026-08-12T11:40:00Z"
    },
    "continuation": {
      "canContinue": true,
      "state": "live",
      "conversation": {
        "fidelity": "live"
      },
      "workspace": {
        "fidelity": "live"
      },
      "environment": {
        "fidelity": "current"
      }
    },
    "phase": "idle",
    "createdBy": {
      "kind": "app_installation",
      "id": "e3f7b219-6c40-4a8e-b591-07d2c48f3a65"
    },
    "createdAt": "2026-08-12T09:20:14Z",
    "updatedAt": "2026-08-12T10:05:52Z"
  }
}

400

Malformed request

application/json

Failure body returned with every non-2xx JSON response; branch on the machine code, never on prose or on the HTTP status alone.

object

error

required

Stable machine code

string

requiredScope

The installation capability the presented credential lacks, returned with insufficient_scope so an integrator knows exactly which capability to request

string

retryAfterSeconds

Advisory seconds to wait before retrying; returned on rate-limit denials, where the Retry-After header carries the same value

integer

>= 1

key

additional properties

any

Example

{
  "error": "invalid_request"
}

404

The resource is missing or inaccessible

application/json

Failure body returned with every non-2xx JSON response; branch on the machine code, never on prose or on the HTTP status alone.

object

error

required

Stable machine code

string

requiredScope

The installation capability the presented credential lacks, returned with insufficient_scope so an integrator knows exactly which capability to request

string

retryAfterSeconds

Advisory seconds to wait before retrying; returned on rate-limit denials, where the Retry-After header carries the same value

integer

>= 1

key

additional properties

any

Example

{
  "error": "cloud_session_not_found"
}

409

Idempotency, lifecycle, revision or single-flight conflict

application/json

Failure body returned with every non-2xx JSON response; branch on the machine code, never on prose or on the HTTP status alone.

object

error

required

Stable machine code

string

requiredScope

The installation capability the presented credential lacks, returned with insufficient_scope so an integrator knows exactly which capability to request

string

retryAfterSeconds

Advisory seconds to wait before retrying; returned on rate-limit denials, where the Retry-After header carries the same value

integer

>= 1

key

additional properties

any

Example

{
  "error": "cloud_session_conflict"
}

Update Session presentation or execution defaults

Authorizations

Parameters

Path Parameters

Example

Request Bodyrequired

Example

Responses

200

Example

400

Example

404

Example

409

Example

Request Body^required