DocsDevelop

Interactions

Create structured requests, collect responses, and deliver outcomes to whoever asked.

The interactions API creates structured requests for information, approval, or review. An assistant can ask from a conversation and get the outcome back there, an HTTP subscriber can receive the resolved callback, and an application can create a standalone inbox item.

Request protocols

ProtocolUse when
request_informationThe consumer needs text, one option, or several options.
request_approvalThe consumer needs permission to continue.
request_reviewThe consumer needs a verdict or notes on a subject.
assign_workThe consumer is handing someone work to do, not a question to answer.

The spec is a list of 1 to 12 questions, answered together as one form. Each question carries a stable id (answers come back keyed by it), a prompt, required (true unless you say otherwise), and a mode that controls how the answer is collected:

ModeCompatible protocols
confirmrequest_approval
selectEvery protocol
multi_selectrequest_information, assign_work
inputrequest_information, request_review, assign_work

request_approval carries exactly one question; a single question is what makes an approval auditable.

Group everything you need into one interaction rather than opening several: each one is a separate item in someone's inbox and a separate interruption. Use stable option values for application logic and human-readable labels for the responder, and set min_selections / max_selections and allow_other rather than writing those rules into the prompt text.

Create an interaction

POST /v1/interactions
{
  "kind": "request_approval",
  "title": "Approve the production deploy?",
  "description": "Review the run evidence before answering.",
  "target_user_ids": ["<principal-id>"],
  "resolution_policy": {
    "type": "any_of"
  },
  "spec": {
    "questions": [
      {
        "id": "decision",
        "prompt": "Approve the production deploy?",
        "mode": "confirm",
        "required": true,
        "default_confirmed": false
      }
    ]
  },
  "expires_at": "<rfc3339-timestamp>"
}

any_of resolves after the first eligible response. all_of waits for every target. quorum resolves after the configured number of distinct targets.

Respond and inspect

GET /v1/interactions
GET /v1/interactions/{interaction_id}
POST /v1/interactions/{interaction_id}/respond
POST /v1/interactions/{interaction_id}/cancel

A responder submits one complete answer set, keyed by question id. Every required question must be answered; there is no partial submit.

{
  "action": "submit",
  "answers": [{ "question_id": "decision", "value": "approved" }],
  "comment": "Evidence checked."
}

Each mode uses exactly one content field. confirm uses value, which must be approved or rejected. select takes exactly one of value or other. multi_select takes values, optionally alongside other. input uses text. other is only accepted on a question with allow_other.

The first response that satisfies the resolution policy freezes the outcome. Mobius marks the interaction completed and notifies its waiting consumer. Resolution counts responders, never questions: all_of waits for every target to submit their whole answer set.

An interaction created through this endpoint is a business request. It does not authorize a built-in integration or MCP action by itself, and Mobius does not create another approval automatically when an assistant calls one of those actions. Put any required review in the workflow, then check the response before making the external call.

Consumers and delivery

The consumer says what waits for the outcome:

ConsumerBehavior
agent_toolReturns the outcome to the conversation where the assistant asked, whether or not a turn is waiting on it.
http_subscriberSends the resolved outcome to an external callback.
noneKeeps a durable request with no automatic continuation.

Work > Inbox is the default delivery surface. Optional email delivery can notify responders who do not keep the app open. Keep the app as the response system of record so identity and audit history remain attached.

Terminal states

completed, expired, and cancelled are terminal. pending and in_review are open states. Expiry or cancellation is delivered to the consumer as a terminal outcome, and that consumer decides its fallback. Cancelling an assistant's question is how a person dismisses it, and the assistant is told. The assistant can also withdraw its own question with mobius.interaction.cancel.

Next