Create a caller-owned Session idempotently
const url = 'https://example.com/v1/sessions/9f2b7c14-59d3-4f7a-b8e1-2a6c05d4e731';const options = { method: 'PUT', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"title":"Rate limit the payments endpoint","task":"Add rate limiting to the payments endpoint and open a PR","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","baseBranch":"main"},"model":"claude-opus-5","runtime":"wamp"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request PUT \ --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", "task": "Add rate limiting to the payments endpoint and open a PR", "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", "baseBranch": "main" }, "model": "claude-opus-5", "runtime": "wamp" }'The first prompt is submitted as a separate Turn. Repeating the same id and immutable body returns the existing Session; changing the body returns a conflict.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”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.
Example
9f2b7c14-59d3-4f7a-b8e1-2a6c05d4e731A UUID you mint and own; it is the idempotency key for creation and the address of every Turn, artifact and publication underneath
Request Bodyrequired
Section titled “Request Bodyrequired”Body of the idempotent Session create. Repeating the same caller-owned id with the same body returns the existing Session; the same id with a different body is a conflict.
object
Human-facing Session name; when omitted a title is derived from task
The durable statement of what this Session is for — creating the Session does not run it, so the first prompt is still submitted as a Turn
Correlation metadata linking this Session to the originating record in the caller’s product
object
Stable opaque identifier for the external tenant the work belongs to, not its display name
The caller’s own kind name for the originating record, such as ticket or issue
The caller’s stable opaque id for that record, so a Session can always be traced back to the business object
Stable one-way hash of the external tenant/user pair; never raw PII.
Short human-readable name for the originating record, shown when the Session is handed to a person
HTTPS deep link back to the originating record in the caller’s product
Repository to check out into the sandbox; a grant source pins the Session to that exact repository, branch and base commit
object
object
object
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.
Required for native WAMP. Omit with a runtime-managed agent to use that runtime’s default model.
Agent runtime id taken from /v1/capabilities, such as wamp, claude-code or codex; it settles at creation and cannot be changed once a Turn is accepted
Example
{ "title": "Rate limit the payments endpoint", "task": "Add rate limiting to the payments endpoint and open a PR", "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", "baseBranch": "main" }, "model": "claude-opus-5", "runtime": "wamp"}Responses
Section titled “Responses”Idempotent replay
Envelope returned by every single-Session read and write.
object
The Session as it stands after this request; a create that was an idempotent replay returns the already-stored Session unchanged
object
The caller-owned Session id, unchanged from the create request
Canonical first-party browser URL for handing this Session to a human
Organization that owns the Session; every credential is authorized against this organization
Human-facing name — the supplied title, or one derived from task when none was given
Correlation metadata supplied at creation; absent when none was sent
object
Stable opaque identifier for the external tenant the work belongs to, not its display name
The caller’s own kind name for the originating record, such as ticket or issue
The caller’s stable opaque id for that record, so a Session can always be traced back to the business object
Stable one-way hash of the external tenant/user pair; never raw PII.
Short human-readable name for the originating record, shown when the Session is handed to a person
HTTPS deep link back to the originating record in the caller’s product
Repository checked out into the sandbox, with the exact base the Session was pinned to; absent for a Session with no repository
object
object
object
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.
Lowercase hex 40-character Git object id naming an exact commit or tree in the source repository.
Model in effect for the next Turn; absent when a runtime-managed agent supplies its own default
The settled foreign agent runtime id, such as claude-code or codex; absent means the native WAMP runtime
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
Whether and at what fidelity this Session can be carried into another Run
object
Whether a new Turn can be admitted for this Session; false only while state is unavailable
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
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 the working tree would be restored at — live, portable_tree from a checkpointed tree, or none
object
Always current: a restore lands in the currently promoted execution environment, and Cloud never claims it retained a specific image or runtime digest
object
The Run whose completion sealed the checkpoint this projection describes; absent when no checkpoint exists
Why continuation is impossible — checkpoint_unavailable, conversation_not_restorable, or workspace_not_restorable; present only when canContinue is false
Last execution phase the runner reported (idle, provisioning, running, awaiting, finalizing, completed, failed); advisory presentation state — read the Run for authoritative status
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
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.
Present only while a Run is queued, dispatching or running — this is the id to cancel
object
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.
When the Session was admitted
Last time durable Session state changed; the Session list is ordered by this value descending
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": "running", "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:41:02Z" }}Session created
Envelope returned by every single-Session read and write.
object
The Session as it stands after this request; a create that was an idempotent replay returns the already-stored Session unchanged
object
The caller-owned Session id, unchanged from the create request
Canonical first-party browser URL for handing this Session to a human
Organization that owns the Session; every credential is authorized against this organization
Human-facing name — the supplied title, or one derived from task when none was given
Correlation metadata supplied at creation; absent when none was sent
object
Stable opaque identifier for the external tenant the work belongs to, not its display name
The caller’s own kind name for the originating record, such as ticket or issue
The caller’s stable opaque id for that record, so a Session can always be traced back to the business object
Stable one-way hash of the external tenant/user pair; never raw PII.
Short human-readable name for the originating record, shown when the Session is handed to a person
HTTPS deep link back to the originating record in the caller’s product
Repository checked out into the sandbox, with the exact base the Session was pinned to; absent for a Session with no repository
object
object
object
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.
Lowercase hex 40-character Git object id naming an exact commit or tree in the source repository.
Model in effect for the next Turn; absent when a runtime-managed agent supplies its own default
The settled foreign agent runtime id, such as claude-code or codex; absent means the native WAMP runtime
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
Whether and at what fidelity this Session can be carried into another Run
object
Whether a new Turn can be admitted for this Session; false only while state is unavailable
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
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 the working tree would be restored at — live, portable_tree from a checkpointed tree, or none
object
Always current: a restore lands in the currently promoted execution environment, and Cloud never claims it retained a specific image or runtime digest
object
The Run whose completion sealed the checkpoint this projection describes; absent when no checkpoint exists
Why continuation is impossible — checkpoint_unavailable, conversation_not_restorable, or workspace_not_restorable; present only when canContinue is false
Last execution phase the runner reported (idle, provisioning, running, awaiting, finalizing, completed, failed); advisory presentation state — read the Run for authoritative status
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
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.
Present only while a Run is queued, dispatching or running — this is the id to cancel
object
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.
When the Session was admitted
Last time durable Session state changed; the Session list is ordered by this value descending
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": "unavailable" }, "continuation": { "canContinue": true, "state": "fresh", "conversation": { "fidelity": "none" }, "workspace": { "fidelity": "none" }, "environment": { "fidelity": "current" } }, "phase": "idle", "createdBy": { "kind": "app_installation", "id": "e3f7b219-6c40-4a8e-b591-07d2c48f3a65" }, "createdAt": "2026-08-12T09:20:14Z", "updatedAt": "2026-08-12T09:20:14Z" }}Headers
Section titled “Headers”Malformed request
Failure body returned with every non-2xx JSON response; branch on the machine code, never on prose or on the HTTP status alone.
object
Stable machine code
The installation capability the presented credential lacks, returned with insufficient_scope so an integrator knows exactly which capability to request
Advisory seconds to wait before retrying; returned on rate-limit denials, where the Retry-After header carries the same value
Example
{ "error": "invalid_request"}Idempotency, lifecycle, revision or single-flight conflict
Failure body returned with every non-2xx JSON response; branch on the machine code, never on prose or on the HTTP status alone.
object
Stable machine code
The installation capability the presented credential lacks, returned with insufficient_scope so an integrator knows exactly which capability to request
Advisory seconds to wait before retrying; returned on rate-limit denials, where the Retry-After header carries the same value
Example
{ "error": "cloud_session_conflict"}The pre-authentication edge budget or durable human-membership/App-installation budget is exhausted
Failure body returned with every non-2xx JSON response; branch on the machine code, never on prose or on the HTTP status alone.
object
Stable machine code
The installation capability the presented credential lacks, returned with insufficient_scope so an integrator knows exactly which capability to request
Advisory seconds to wait before retrying; returned on rate-limit denials, where the Retry-After header carries the same value
Example
{ "error": "cloud_rate_limit_exceeded", "retryAfterSeconds": 3}Headers
Section titled “Headers”IETF HTTPAPI structured quota policy
IETF HTTPAPI structured current service limit