Actions

An Action is the record of one Verb run on one Thing. Every write on every Interface returns one, whether code, a model, an Agent or a Human does the work.

Anatomy of an ActionCopy Anchor Link

tutorloop.com is a Startup that matches students with tutors. Its booking Agent places an Order for an algebra hour on behalf of a Customer, and no tutor has claimed it:

{
  "api": "https://api.sb/tutorloop.com",
  "action": {
    "$id": "https://api.sb/tutorloop.com/actions/action_42",
    "$type": "Action",
    "operation": "Order.place",
    "status": "pending",
    "reason": "awaitingWorker",
    "mode": "send",
    "by": "https://api.sb/tutorloop.com/agents/booking",
    "for": "https://api.sb/tutorloop.com/customers/customer_9",
    "via": "mcp",
    "on": null,
    "thing": "https://api.sb/tutorloop.com/orders/order_17@1",
    "input": { "offer": "offer_algebra_hour", "slot": "2026-10-23T16:00:00Z" },
    "createdAt": "2026-10-22T14:03:11Z"
  }
}

The Action never says which Function did the work. tutorloop.com can move tutor matching from a human to an Agent, and no caller sees a change.

Five statusesCopy Anchor Link

An Action is pending until it settles as done, failed, canceled or refused. A settled Action is final, and every status change appends an Event. While pending, its reason says who holds the ball:

A caller that sees awaitingInput acts. A caller that sees any other reason waits.

Rejected at the door, or refused on the recordCopy Anchor Link

Where a call fails decides whether an Action exists. Malformed input, an unknown Verb, a missing key and a throttled request are rejected at the door. They return a problem document and record nothing.

A call the Thing itself declines is an Action born refused, with the reason on the record. A booking for a slot already taken, or a Mandate that does not cover the Customer, refuses this way. The refusal stays in history next to every Action that succeeded.

Waiting for the resultCopy Anchor Link

In do Mode the call holds until the Action settles. In send Mode the call answers 202 at once, with the Action's URL in Location.

To follow a sent Action, read it again. Prefer: wait=30 holds the read for up to 30 seconds until the Action settles:

curl https://api.sb/tutorloop.com/actions/action_42 \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Prefer: wait=30"

In the SDK, .settled resolves to the final Action whatever its status. For work that takes hours, a Watch on Order.placed delivers the Event when it lands. Webhooks covers delivery.

Windows and ApprovalsCopy Anchor Link

Some Actions wait on purpose. A one-way Verb, such as a refund or an ad spend, waits awaitingTime in its delay window. Watchers can pause, redirect or cancel it, and with no intervention it runs when the window closes.

An Action over a Limit waits awaitingAction on an Approval. The Approval covers exactly the input and Thing Version the approver saw. If the Thing changes first, the Action is refused and a fresh call needs a fresh Approval.

To learn whether a call waits before making it, preview it in try Mode. The preview returns the status the Action would reach, its window, and whether it needs an Approval.

Retries and historyCopy Anchor Link

A failed Action stays failed. Action.retry starts a new Action whose on points at the old one, so the record shows both attempts. To undo a done Action, run the Verb that reverses it, such as a refund after a payment.

Nothing rewrites an Action. Every Action is kept forever, and its Events replay the history of every Thing it touched.

NextCopy Anchor Link

• Idempotency: send a write twice and get one Action.
• Modes: how try, send and do change what a caller sees.
• The response envelope: the response an Action arrives in.