Skip to content

by Startups.Studio

Core grammar Action

Action.ask

POST /{namespace}/actions/{action}/ask

Ask puts a Question to a Party, a Role, or a Worker and holds the Action `pending` with reason `awaitingInput`.

Noun: Action
Mode: do
Event: Action.asked

You, to your agent

Ask the latest action with a thing.

curl -X POST https://api.sb/routewise.dev/actions/action_1/ask \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"thing_1","text":"Example text"}'

import { $ } from 'startup-builder'

const { question, action } = await $.Action.ask({ action: 'action_1', to: 'thing_1', text: 'Example text' })

npx startup-builder do Action.ask --json '{"action":"action_1","to":"thing_1","text":"Example text"}'

{
  "name": "do",
  "arguments": {
    "code": "return await $.Action.ask({ action: 'action_1', to: 'thing_1', text: 'Example text' })"
  }
}

Ask puts a Question to a Party during an Action and holds it pending with reason awaitingInput until it is answered.

Inputs

Input	Type	Required	Description
`action`	Action	required	The Action that needs an answer to go on.
`to`	Thing	required	Who is asked: a Party, a Role, or a Worker.
`text`	`text`	required	The question, in one message.
`choices`	`string[]`		The answers offered.
`schema`	`json`		The typed answer’s shape.
`answerBy`	`datetime`		When the Action’s timeout rule applies.

Outputs

Output	Type	Required	Description
`question`	Question	required	The Question, posted in the record’s Thread.
`action`	Action	required	The Action, now pending with reason `awaitingInput`.

Effects

Emits Action.asked.
Two-way: it runs at once, in the try, send and do modes.
Pauses an Order’s delivery window and service level while the Customer is the one asked.
Renders as a Portal form, an email, a chat card, or an MCP elicitation, by where the asked party is.

Refuses when

Check	Error	Fix	Then call
The key is valid, but its scopes do not allow this operation.	`forbidden`	Use a key whose scopes cover the operation, or ask an owner of the namespace to grant them.	Action.ask

When it waits

Gate	Default
Decision class	Low: two-way, nothing at stake
Delay window	None: it runs once review passes.
Limit	The call Limit of the Permission it runs under.
Over the Limit	It waits `pending` for an Approval from the Founder. Approved, it runs; refused, it ends `refused` with `limit-exceeded`; unanswered by its deadline, it ends `canceled`.

Action.answer

Previous Page

Action.attest

Next Page