Background actions

Background actions run a Verb durably after the call returns. The caller gets a pending Action at once, and the platform orders, retries and finishes the work.

ContractCopy Anchor Link

• A call in send Mode returns 202, the pending Action and its Location.
• While pending, the Action's reason names who holds the work: queued, running, retrying, or an Awaiting reason.
• A failed attempt retries with backoff, 5 attempts over 24 hours by default. Each retry is a new Action linked to the first.
• An Idempotency-Key makes a repeated send return the first Action. A step with an outside effect checks whether the effect happened before it repeats.
• Work for a Worker is a Task, leased by atomic claim. A lease that misses its heartbeat returns the Task to the queue, and after 3 lost leases the Task escalates.
• Concurrency per Verb is a Setting.
• An Action that exhausts its retries ends failed and stays readable. Action.retry starts it again from the record.

VerbsCopy Anchor Link

InterfacesCopy Anchor Link

• API
• SDK
• CLI
• MCP

ExampleCopy Anchor Link

# castnotes.example, a podcast-transcription API, declares an `Episode` Noun. It queues a three-hour episode, then reads the Action.
curl -X POST "https://api.sb/castnotes.example/episodes/ep_77/transcribe?mode=send" \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Idempotency-Key: ep_77-v1"

npx startup-builder show /actions/action_9031