An interaction is a request for a human or agent actor to take an action. When linked to a run, completing the interaction delivers a signal that resumes the suspended workflow. Without a run link, an interaction acts as a standalone inbox item with no resume side effect.

The model

Each interaction has:

• A type — approval, review, or input. The type sets the semantic intent: approvals gate a binary decision, reviews collect a structured choice, and input interactions collect free-form or multi-option values.
• A spec — the rendering contract that controls the UI affordance. The mode field must be compatible with the type: approval requires confirm; review requires select; input supports select, multi_select, or input.
• A target actor — the member, agent, or group the interaction is routed to.
• For group targets, a routing policy — first_responder (one member claims the interaction and responds) or all_members (every snapshotted member must respond before the interaction completes).
• An optional run link — a run_id and topic pair. When both are set, completing the interaction delivers a signal on that topic and resumes the suspended run.

An approval gate on a deployment

The following request creates a run-backed approval interaction routed to a specific member:

curl -X POST /v1/projects/acme/interactions \
  -H "Authorization: Bearer $MOBIUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "approval",
    "run_id": "run_01abc",
    "topic": "deploy-gate",
    "target_actor": { "type": "member", "id": "user_alice" },
    "message": "Approve deployment of service-api to production?",
    "spec": { "mode": "confirm" },
    "expires_at": "2026-04-22T10:00:00Z"
  }'

Mobius creates the interaction in pending status and surfaces it in Alice's inbox. When Alice responds, Mobius marks the interaction completed and delivers a signal on the deploy-gate topic, resuming the suspended run. If Alice does not respond before expires_at, the interaction transitions to expired.

Lifecycle

Where you see it

• Dashboard — Projects → <project> → Interactions lists pending, completed, and expired interactions. The inbox view shows only interactions routed directly to you or to a group you belong to.
• API — the Interactions tag group. Key operations are createInteraction, respondToInteraction, claimInteraction, and releaseInteraction.

See also

• Runs — the workflow executions that interactions can suspend and resume.
• Signals — the mechanism interactions use to resume a suspended run.
• Actions — how worker actions create interactions from within a job.