Take Agent Discovery Turn
POST /agent/onboarding/discovery/turn
One conversational turn of the kickoff. THIS ONE COSTS MONEY.
The only route on this surface that makes an LLM call, which is why it is
tiered billable and why the app rate-limits it at 20 requests a minute
per organisation - far above a human conversation, far below anything that
shows up on a bill. Over that, the app answers 429 with Retry-After.
The model replies AND states what it learned in one forced tool call, so a
message that answers four questions records four fields. Everything it
claims is validated before it is written: a key outside the framework is
dropped, and a green with no supporting quote is DOWNGRADED to amber
rather than trusted.
The turn writes only to the discovery record. It provisions nothing, calls no tools, and sends nothing.
There is no history parameter and that is deliberate - see the module
docstring.
Authorizations
Parameters
Header Parameters
Request Body required
Mirror of DiscoveryTurnRequest.
There is deliberately NO history field, and that is load-bearing rather
than an omission. The app removed one: the panel used to keep the
transcript in browser state and ship it back on every turn, so a reload
destroyed the customer’s whole kickoff. The server re-grounds from the
durable record instead. A caller-supplied transcript is not something the
server can verify, and accepting one here would re-open exactly that hole.
Responses
200
Successful Response
object
An open envelope for an onboarding or discovery result.
Open on purpose. Discovery state carries a per-field coverage matrix whose field set is the product’s own onboarding questionnaire - it changes as the questionnaire does, and a pinned mirror would silently DROP a field the customer had answered. On a surface whose whole job is “what do we still not know about you”, a dropped field reads as an answered question.
object
object
Whether there are more pages
Items per page
Current page number (1-indexed)
Total number of items
422
Validation Error