API

Interactions

The interactions API creates structured requests for information, approval, or review. A loop step or agent tool can wait on the result, and an application can also create a standalone inbox item.

Request protocols

Protocol	Use when
`request_information`	The consumer needs text, one option, or several options.
`request_approval`	The consumer needs permission to continue.
`request_review`	The consumer needs a verdict or notes on a subject.

The response spec.mode controls how the answer is collected:

Mode	Compatible protocols
`confirm`	`request_approval`
`select`	All three protocols
`multi_select`	`request_information`
`input`	`request_information`, `request_review`

Use stable option values for application logic and human-readable labels for the responder.

Create an interaction

POST /v1/projects/{project}/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": {
    "mode": "confirm",
    "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/projects/{project}/interactions
GET /v1/projects/{project}/interactions/{interaction_id}
POST /v1/projects/{project}/interactions/{interaction_id}/respond
POST /v1/projects/{project}/interactions/{interaction_id}/cancel

The first response that satisfies the resolution policy freezes the outcome. Mobius marks the interaction completed and notifies its waiting consumer.

Consumers and delivery

The consumer says what waits for the outcome:

Consumer	Behavior
`run`	Resumes a waiting loop step.
`agent_tool`	Returns the answer to a waiting agent tool call.
`http_subscriber`	Sends the resolved outcome to an external callback.
`none`	Keeps a durable request with no automatic continuation.

The app 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 is the only live state. A loop interaction step decides whether expiry or cancellation fails the run or follows another authored path.

Design the human experience with interactions.
Use interaction commands from the CLI command reference.
Inspect every schema in the interactive API reference.