Endpoint
PUT
/v1/stable/conversation/{userID}

Send one action to test your agent against a draft or published environment. Use launch to start the conversation, then text to send a user message.

Request examples

Start a conversation by sending a launch action to this endpoint. Launch is a request type, not a separate route.

Request body
{
  "action": {
    "type": "launch"
  },
  "version": "draft"
}
Request
Response

Path parameters

userID
string
required

The ID identifying this conversation. Any stable string you choose; the same value addresses the same conversation on every call.

Query parameters

projectID
string
required

The ID of the project to operate on.

environmentAlias
string
required

The alias of the environment to operate on (e.g. main).

Request body

action
object
required
AnyRequest — see its attributes above
version
enum<string>
required

Whether to run the conversation against the draft or published version of the environment.

Available options: draft, published
More parameters
sessionID
string

The unique ID of the conversation session to continue.

config
object

Options controlling how the response is shaped.

Response

200 - application/json

Returns the agent's response to the turn as an array of traces, each a typed piece of the reply such as text, speech, a card or carousel, a choice, a tool call, or a debug entry.

traces
object[]
required
AnyTrace — see its attributes above
needsRecompile
boolean
required

When true, this turn ran against a stale prototype. Compile the environment and send again; do not treat these traces as proof the latest edits work.

Endpoint
POST
/v1/stable/conversation/script

Test a short conversation in one request. The script launches the agent automatically, then sends your messages in order and returns the results.

Request
Response

Query parameters

projectID
string
required

The ID of the project to operate on.

environmentAlias
string
required

The alias of the environment to operate on (e.g. main).

Request body

messages
object[]
required

The user messages to send, in order, after the launch. A message is typed text, as a string or { "text": "…" }, or a button press, as { "button": "<label>" }, for a button the reply before offered. The digest shows offered buttons as "[buttons: Yes | No]".

Minimum items: 1 · Maximum items: 10
variables
object

Variable values to set before the launch, keyed by variable name, to start as a known caller. Next to messages, not inside launch.

version
enum<string>
default:"draft"

Whether to talk to the draft or the published version of the environment. Draft unless you pass it.

Available options: draft, published
launch
object

How the conversation starts; payload is its only field. Leave it out for a plain launch.

userID
string

The conversation user ID to run as; the agent reads it as the user_id variable. Use it when the agent expects a caller ID of a known shape, such as a phone number, and make one up: never a real customer's ID. Draft version only. Leave it out to run as a new user each time. A reused ID keeps the variables an earlier conversation with it left.

Minimum length: 1 · Maximum length: 128

Response

200 - application/json

Returns one digest per turn: the agent's replies, the tools it called, the variables that changed, and any errors. Messages that were not sent because the script stopped early come back in notSent, and needsRecompile says whether the turns ran against an outdated compile.

userID
string
required

The conversation user ID the script ran as, for reading its state afterwards.

transcriptID
string
required

The transcript this conversation is saved to, for reading its logs. Null when the runtime reported none, for example when the project does not save test conversations; then search transcripts with sessionID set to userID.

needsRecompile
boolean
required

When true, the script ran against a stale prototype. Compile the environment and run it again; do not treat these turns as proof the latest edits work.

turns
object[]
required

The launch turn first, then one turn per message sent.

StableConversationScriptTurn — see its attributes above
notSent
string[]
required

Steps that were not run, in the same form as user, because the conversation ended, a send failed, a button was not on offer, the runtime logged an error outside a tool or a fatal error, the credit limit was reached, or the caller stopped the script first. A failed tool or HTTP call does not stop the script: it is listed in its turn.

Current - 2026/04
Start a session through the Agent runtime first, then send this request with the returned session key. This REST endpoint is included here for testing; use the Agent runtime for production and streaming integrations.
Endpoint
POST
/v4/interact

Send one action directly to the conversation runtime over REST. Choose the current or legacy contract above; the current contract requires a session key, while legacy uses your API key and user ID.

Request examples

Start a conversation by sending a launch action to this endpoint. Launch is a request type, not a separate route.

Request body
{
  "action": {
    "type": "launch"
  }
}
Request
Response

Authentication

authorization
string
header
required

Session key returned from the start session endpoint.

Request body

action
object
required

The user's action for this conversation turn. Most commonly, the text action is used to send a message to the agent as a user.

variables
object

Key-value pairs to set or update on the session before this turn is processed. Useful for injecting context like a user's name, account tier, or current page. Learn more.

state
any
config
object

Optional settings for this turn.

Response

200 - application/json
traces
object[]
required

An array of traces that occurred during this turn.

TestingRuntime_AnyTrace — see its attributes above

Error 402

application/json

Returned when the turn produces nothing but a credit_limit_reached debug trace (the account has exhausted its available credits). The response body has the same shape as a 200 response.

traces
object[]
required

An array of traces that occurred during this turn.

TestingRuntime_AnyTrace — see its attributes above

Schemas

Use the up and down arrow keys to select a result, Enter to open it, and Escape to close the search.