Skip to content
WAMP Cloud

List actionable human-input requests

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

Requires wamp.cloud.sessions:read. Returns only the currently open requests, oldest first, and is not paged — it is the actionable edge to render after a reconnect, not history; resolved and expired Interactions are recoverable from the event log instead. Answer one by submitting a Turn with replyTo.interactionId set to the id here, which is an engine-scoped string rather than a UUID. kind: "ask_user" carries a request.questions array to render, while exit_plan_mode carries no request and just needs approval or redirection in prose. An empty array while the Run status is awaiting means the Interaction expired, so the Run needs a plain Turn to continue.

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”

Open Interactions

Media typeapplication/json
object
interactions
required
Array<object>

A request for human input that has parked its Run in awaiting. Answer it with an ordinary Turn carrying replyTo; the listing endpoint returns only the ones still open.

object
id
required

Opaque runtime-assigned interaction id, unique within its Session; send it back verbatim as replyTo.interactionId

string
sessionId
required

Session this request belongs to

string format: uuid
runId
required

Run that opened the request and that resumes once it is answered

string format: uuid
kind
required

ask_user for a bounded multiple-choice question, exit_plan_mode for approval of a proposed plan

string
Allowed values: ask_user exit_plan_mode
status
required

open while it still needs an answer, resolved once a Turn answered it, expired when the workspace was lost, the Run was cancelled, or the Session was archived

string
Allowed values: open resolved expired
request

Sanitized question payload — for ask_user, bounded questions each with at least two options and optional header and recommended choice; absent for exit_plan_mode

object
key
additional properties
any
response

The Turn that answered this request; present once status is resolved

object
turnId

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
openedAt
required

When the agent opened the request

string format: date-time
resolvedAt

When the answering Turn was admitted; absent unless resolved

string format: date-time
expiredAt

When the request stopped being answerable; absent unless expired

string format: date-time
Example
{
  "interactions": [
    {
      "id": "toolu_01H8sZ4kQm2rVn9pXfB3tGdA",
      "sessionId": "9f2b7c14-59d3-4f7a-b8e1-2a6c05d4e731",
      "runId": "c47a1e08-3d6b-4a92-9f15-8b70d2e5c6a4",
      "kind": "ask_user",
      "status": "open",
      "request": {
        "questions": [
          {
            "question": "Which limiter should the payments endpoint use?",
            "header": "Rate limiting strategy",
            "options": [
              "Fixed window",
              "Sliding window",
              "Token bucket"
            ],
            "recommendedIndex": 1,
            "multiSelect": false,
            "allowCustom": true
          }
        ]
      },
      "openedAt": "2026-08-12T09:44:38Z"
    },
    {
      "id": "toolu_01K2mWpR7yLd4bQx9sTfNvHe",
      "sessionId": "9f2b7c14-59d3-4f7a-b8e1-2a6c05d4e731",
      "runId": "c47a1e08-3d6b-4a92-9f15-8b70d2e5c6a4",
      "kind": "exit_plan_mode",
      "status": "open",
      "openedAt": "2026-08-12T09:45:02Z"
    }
  ]
}

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"
}