Skip to content
WAMP Cloud

Read one Session projection

GET
/v1/sessions/{sessionId}
curl --request GET \
  --url https://example.com/v1/sessions/9f2b7c14-59d3-4f7a-b8e1-2a6c05d4e731 \
  --header 'Authorization: Bearer <token>'

Requires wamp.cloud.sessions:read. This is a projection, not a live status feed: phase is the last phase the server recorded, so poll the event log rather than this field when you need ordering. Two fields carry the decisions a caller has to make — workspace.state says whether the sandbox is still attached (and until when), and continuation says whether a further Turn can resume exactly, resume from a portable checkpoint, or not at all. activeRun is present only while a non-terminal Run exists, and at most one ever does. A Session that is archived, or that belongs to another installation, is 404 either way.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “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

Responses

Section titled “Responses”

200

Section titled “200”

Session

Media typeapplication/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
id
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
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
id
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
id
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",
    "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-opus-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": "awaiting",
    "createdBy": {
      "kind": "app_installation",
      "id": "e3f7b219-6c40-4a8e-b591-07d2c48f3a65"
    },
    "activeRun": {
      "id": "c47a1e08-3d6b-4a92-9f15-8b70d2e5c6a4"
    },
    "createdAt": "2026-08-12T09:20:14Z",
    "updatedAt": "2026-08-12T09:44:38Z"
  }
}

404

Section titled “404”

The resource is missing or inaccessible

Media typeapplication/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"
}