Skip to main content
POST
Submit tool-call input

Authorizations

Authorization
string
header
required

Personal access token, sent as Authorization: Bearer <token>. Each operation lists the permission it needs: read_only or full_access. A full-access token can call every operation. A read-only token can call only the operations that list read_only; anything else returns 403 read_only_credential_route_not_allowed.

Scopes

full_access
PersonalAccessTokenAuth
full_access
WorkspaceApiKeyAuth
full_access
WorkspaceApiKeyBearerAuth

Headers

X-Active-Branch-Id
string

ID of the branch the editor shows. Used when branch_id is omitted, for users who work on protected-main branches.

Idempotency-Key
string

A value you choose for this send, such as a UUID. A retry carrying the same value within 10 minutes is ignored rather than run again. Takes precedence over X-Request-ID.

Path Parameters

app_id
string
required

ID of the app whose AI chat this request acts on.

Query Parameters

branch_id
string

ID of the branch to work on, as returned by List branches. Omit it to work on the app's main branch.

Body

application/json
tool_call_id
string
required

ID of the tool call to answer. Read it off the waiting assistant message returned by Read conversation messages.

Example:

"toolu_01A9FJd3kP2mNqRs7VwXyZ4b"

action
enum<string>
required

Whether to let the tool call run or turn it down. Rejecting tells the AI to continue without doing that step.

Available options:
approved,
rejected
Example:

"approved"

extra_user_input
Extra User Input · object | null

What the user answered, for a tool call whose waiting_on.kind is choice or input. Its shape is the tool's: a choice question takes {"answers": [...]}, one entry per answered question with its question_index and a selected_label, selected_labels or custom_text, and a secrets request takes {"secrets": {"NAME": "value"}}. Leave it out for an approval call or a rejection, except a rejection a workspace rule caused, which may take {"workspace_rule_reason": "..."} with the rule's reason so the AI is told a rule refused it rather than the user.

nonblocking_cards
boolean
default:false

Set to true when the AI may have kept working after it asked. The answer is then accepted until the user sends a new request, even after later AI replies or a stopped turn, and the AI goes on once every tool call still waiting in that turn is answered. While that turn is still running, the request returns as soon as the answer is kept, and the turn applies it. When false, an answer is refused once the user sent another message or stopped the turn. Ignored for users whose AI always stops to wait for an answer.

Response

Successful Response

An app, with its conversation and build status.

id
string | null

ID of the app.

Example:

"6820f3a4e7b91d003c45a1f2"

name
string | null

Display name of the app.

Example:

"My CRM"

status
StatusObject · object | null

The app's build status once the request returned. Read state to tell a finished turn from one that is still processing or that failed.

conversation
ChatTurnConversation · object | null

The app's conversation, including the messages this request produced.