Flow

Send the next message

POST
/builds/{build}:send

Sends the build's next message, which the agent reads with the whole conversation so far: a prompt once the build is IDLE, or the answer to the question it waits on (AWAITING_INPUT).

BearerAuth
headerAuthorizationBearer <JWT>

Admin token, API token issued via /api-tokens, or an OIDC JWT access token issued by the configured OIDC provider.

build*string

Build identifier (UUID).

Formatuuid
application/json
  1. body

The user's next message, exactly one of prompt and answer.

prompt?string

What the user asks the agent, in plain words.

Length1 <= length <= 32768
integrations?array<>

With prompt only. Integration hints: the integrations, actions and triggers the user wants the flow to use, picked from GET /integrations/catalog, as <name> or <name>#<export> (slack, slack#sendMessage). The agent is told of them and decides; a hint the catalog doesn't have is passed on as given. Kept on the user's message in messages, as a data-integrations part.

Itemsitems <= 32
answer?

The answer to the agent's question, or its decline. Give one answer per question, in order: for a question without options, text; for a single-select one, one label in selected or text alone; for a multi-select one, any of its labels, text, or both.

Response Body

The build, running the message.

application/json
  1. response

A build of a flow: a conversation with the build agent, which writes the flow's code in a project of the build's own.

name*string

Unique resource name.

flow*string

The flow built.

state*string

RUNNING while the agent works on a prompt or an answer; AWAITING_INPUT when it asked question; IDLE once it ended otherwise, ready for the next prompt.

Value in"RUNNING""AWAITING_INPUT""IDLE"
question?

The agent's question (Flash's ask_user_question): up to four questions, answered together.

deploy?string

The deploy of the code the build's last clean prompt wrote: the agent's job indexes that code as a bundle PATCH /flows/{flow} would be, and the deploy has already succeeded once the build leaves RUNNING, so the flow has the code from then on. Code that can't be indexed is not deployed: the build's error says why. Absent before one, and once the deploy is no longer kept. A stale build deploys nothing more.

stale*boolean

Whether the flow was deployed from elsewhere (an upload, another build) since the build started from its code, or since the build's own code last went live. A stale build edits outdated code, so it takes no more prompts or answers (409) and deploys nothing more; start a new build. A deploy that makes a build stale stops the prompt it is running.

error?

Why the build's last prompt failed.

messages?array<>

The conversation, as AI SDK UI messages (UIMessage): the user's prompts (a text part) and answers (a data-answer part), and the agent's message of each prompt or answer, made of the chunk events of GET /builds/{build}/events. Only GET /builds/{build} returns them.

createTime*string

Time at which the build was started.

Formatdate-time
updateTime*string

Time at which the build last changed.

Formatdate-time
Example Request
curl -X POST 'https://example.com/api/hub/builds/497f6eca-6276-4993-bfeb-53cbbbba6f08:send' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "name": "builds/0190f5a2-7c3e-7b1a-9d4e-2f6a8b0c1d3e",  "flow": "flows/550e8400-e29b-41d4-a716-446655440000",  "state": "RUNNING",  "question": {    "toolCallId": "string",    "questions": [      {        "question": "string",        "header": "string",        "options": [          {            "label": "string",            "description": "string"          }        ],        "multiSelect": true      }    ]  },  "deploy": "deploys/0190f5a2-7c3e-7b1a-9d4e-2f6a8b0c1d3e",  "stale": true,  "error": {    "reason": "INPUT",    "message": "string"  },  "messages": [    {}  ],  "createTime": "2019-08-24T14:15:22Z",  "updateTime": "2019-08-24T14:15:22Z"}