Skip to main content
POST
Submit tool-call input (batch)

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_ids
string[]
required

IDs of the tool calls to answer, up to 100. They all get the same action, and a repeated ID is answered once.

Maximum array length: 100
Example:
action
enum<string>
required

Whether to let these tool calls run or turn them down.

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

The app after a batch of tool calls was answered, with one result per call.

results
BatchToolCallResultSummary · object[] | null

One entry per tool call that was answered, in the order they were processed. A repeated ID appears once, so this can be shorter than the list you sent. Empty when the request was a duplicate that had already been applied.

app
ChatTurnResponse · object | null

The app once the resumed turn finished.