> ## Documentation Index
> Fetch the complete documentation index at: https://docs.base44.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Submit tool-call input (batch)
> This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.
Answers several waiting tool calls at once with the same `action`, then resumes the turn. Use it instead of calling [Submit tool-call input](/api-reference/submit-tool-call-input) once per tool call.
Each tool call gets its own entry in `results`, so one of them can fail while the rest succeed. Check every entry rather than assuming the whole batch worked. The app is returned under `app`, not at the top level as it is on the single-tool-call endpoint.
The request stays open until the resumed turn settles, so it can take several minutes. Resuming a turn consumes credits.
Set an `X-Request-ID` header before you send. A network [retry](/developers/references/app-management/get-started/retries) carrying the same value is ignored rather than resumed a second time and charged again. It comes back with an empty `results` array, which means nothing ran again rather than that the tool calls were rejected.
A `200` response does not mean the turn succeeded. Two cases come back as a `200`.
- **The turn ran and finished.** `app.status.state` is `ready` and the app is idle again.
- **The turn ran and failed.** `app.status.state` is `error`, and `app.status.error_source` says where it failed. A value of `paywall` means the app's workspace has no credits left.
The response includes fields beyond the ones documented here. Don't rely on undocumented response fields, as they can change at any time. Send only the fields documented here. Other request fields are not supported and their behavior can change.
## OpenAPI
````yaml /developers/references/app-management/app-management-openapi.json post /api/apps/{app_id}/chat/submit-tool-call-input/batch
openapi: 3.1.0
info:
title: Base44 App Management API
version: 1.0.0
servers:
- url: https://app.base44.com
security:
- ApiKeyAuth: []
paths:
/api/apps/{app_id}/chat/submit-tool-call-input/batch:
post:
summary: Submit tool-call input (batch)
description: >-
This API is in beta. Endpoints, fields, and behavior may still
change, so avoid depending on it in production.
Answers several waiting tool calls at once with the same `action`, then
resumes the turn. Use it instead of calling [Submit tool-call
input](/api-reference/submit-tool-call-input) once per tool call.
Each tool call gets its own entry in `results`, so one of them can fail
while the rest succeed. Check every entry rather than assuming the whole
batch worked. The app is returned under `app`, not at the top level as
it is on the single-tool-call endpoint.
The request stays open until the resumed turn settles, so it can take
several minutes. Resuming a turn consumes credits.
Set an `X-Request-ID` header before you send. A network
[retry](/developers/references/app-management/get-started/retries)
carrying the same value is ignored rather than resumed a second time and
charged again. It comes back with an empty `results` array, which means
nothing ran again rather than that the tool calls were rejected.
A `200` response does not mean the turn succeeded. Two cases come back
as a `200`.
- **The turn ran and finished.** `app.status.state` is `ready` and the
app is idle again.
- **The turn ran and failed.** `app.status.state` is `error`, and
`app.status.error_source` says where it failed. A value of `paywall`
means the app's workspace has no credits left.
The response includes fields beyond the ones documented here.
Don't rely on undocumented response fields, as they can change at any
time. Send only the fields documented here. Other request fields are not
supported and their behavior can change.
operationId: >-
batch_submit_tool_call_input_api_api_apps__app_id__chat_submit_tool_call_input_batch_post
parameters:
- name: app_id
in: path
required: true
schema:
type: string
description: ID of the app whose AI chat this request acts on.
title: App Id
description: ID of the app whose AI chat this request acts on.
example: 6820f3a4e7b91d003c45a1f2
requestBody:
required: true
content:
application/json:
schema:
type: object
title: SubmitToolCallInputBatch
required:
- tool_call_ids
- action
properties:
tool_call_ids:
type: array
items:
type: string
description: >-
IDs of the tool calls to answer, up to 100. They all get the
same `action`, and a repeated ID is answered once.
example:
- toolu_01A9FJd3kP2mNqRs7VwXyZ4b
- toolu_01B8GKe4lQ3nOrSt8WxYzA5c
action:
type: string
enum:
- approved
- rejected
description: Whether to let these tool calls run or turn them down.
example: approved
example:
tool_call_ids:
- toolu_01A9FJd3kP2mNqRs7VwXyZ4b
action: approved
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/BatchToolCallResponse'
'400':
description: >-
The app has unsaved sandbox changes that could not be committed
first. Retry the request.
'401':
description: Missing or invalid credentials.
'403':
description: You don't have access to this app.
'404':
description: App not found.
'409':
description: The app is busy with another operation that blocks this resume.
'422':
description: >-
The request body is missing `tool_call_ids` or `action`, `action` is
not `approved` or `rejected`, or more than 100 IDs were sent.
'503':
description: The server is shutting down. Retry the request.
components:
schemas:
BatchToolCallResponse:
properties:
results:
anyOf:
- items:
$ref: '#/components/schemas/BatchToolCallResultSummary'
type: array
- type: 'null'
title: Results
description: >-
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:
anyOf:
- $ref: '#/components/schemas/ChatTurnResponse'
- type: 'null'
description: The app once the resumed turn finished.
type: object
title: BatchToolCallResponse
description: >-
The app after a batch of tool calls was answered, with one result per
call.
BatchToolCallResultSummary:
properties:
id:
anyOf:
- type: string
- type: 'null'
title: Id
description: ID of the tool call this result is for.
example: toolu_01A9FJd3kP2mNqRs7VwXyZ4b
success:
anyOf:
- type: boolean
- type: 'null'
title: Success
description: Whether this tool call was answered successfully.
example: true
error:
anyOf:
- type: string
- type: 'null'
title: Error
description: >-
Why this tool call could not be answered, or `null` when it
succeeded.
example: Failed to process tool call
type: object
title: BatchToolCallResultSummary
ChatTurnResponse:
properties:
id:
anyOf:
- type: string
- type: 'null'
title: Id
description: ID of the app.
example: 6820f3a4e7b91d003c45a1f2
name:
anyOf:
- type: string
- type: 'null'
title: Name
description: Display name of the app.
example: My CRM
status:
anyOf:
- $ref: '#/components/schemas/AppStatusResponse'
- type: 'null'
description: >-
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:
anyOf:
- $ref: '#/components/schemas/ChatTurnConversation'
- type: 'null'
description: >-
The app's conversation, including the messages this request
produced.
type: object
title: ChatTurnResponse
description: An app, with its conversation and build status.
AppStatusResponse:
properties:
state:
type: string
enum:
- ready
- processing
- error
title: State
description: >-
Where the app is in its build lifecycle. Ready means idle with no
build in progress, processing means the app is being generated or
modified, and error means the last build failed. This tracks
building, not publishing.
example: ready
details:
anyOf:
- type: string
- type: 'null'
title: Details
description: >-
Human readable note about the current state, such as what is being
processed or why it failed, or `null` when there is nothing to
report.
example: Publishing app
request_id:
anyOf:
- type: string
- type: 'null'
title: Request Id
description: >-
ID of the request that last changed the status, or `null` if the
status has never changed. Useful when reporting an issue.
example: a1b2c3d4e5f67890abcdef12
last_updated_date:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Last Updated Date
description: >-
Time the status was last updated, as a UTC timestamp in ISO 8601
format.
example: '2026-08-02T14:30:00Z'
error_source:
anyOf:
- type: string
- type: 'null'
title: Error Source
description: >-
Where the failure originated when `state` is `error`, or `null`
otherwise. A value of `paywall` means the work was blocked because
the app's workspace has no credits left.
example: build
paywall_context:
anyOf:
- $ref: '#/components/schemas/PaywallStatusContextResponse'
- type: 'null'
description: >-
Present when the operation was blocked by a plan limit, describing
what was evaluated, or `null` otherwise.
type: object
required:
- state
title: AppStatusResponse
description: The app's current build status.
ChatTurnConversation:
properties:
id:
anyOf:
- type: string
- type: 'null'
title: Id
description: ID of the conversation.
example: 1f0c2b7a-9d51-4c3e-8a62-7b4d5e6f8a90
messages:
anyOf:
- items:
$ref: '#/components/schemas/ConversationMessageSummary'
type: array
- type: 'null'
title: Messages
description: The conversation's messages once the request finished, oldest first.
type: object
title: ChatTurnConversation
PaywallStatusContextResponse:
properties:
billing_organization_id:
type: string
title: Billing Organization Id
description: ID of the billing organization the paywall was evaluated against.
example: 67e0b12c4d8a3f005b21c9e4
user_id:
type: string
title: User Id
description: ID of the user the paywall was evaluated for.
example: 6706af53b9c1e2004a37d85f
evaluated_at:
type: string
format: date-time
title: Evaluated At
description: >-
Time the paywall condition was evaluated, as a UTC timestamp in ISO
8601 format.
example: '2026-08-02T14:30:00Z'
type: object
required:
- billing_organization_id
- user_id
- evaluated_at
title: PaywallStatusContextResponse
ConversationMessageSummary:
properties:
id:
anyOf:
- type: string
- type: 'null'
title: Id
description: ID of the message.
example: 7f3a1c88-52d4-4a0e-9b31-2c6f0d8e4a19
role:
anyOf:
- type: string
enum:
- user
- assistant
- system
- type: 'null'
title: Role
description: >-
Who produced the message. A `user` message is a prompt sent to the
AI, an `assistant` message is the AI's reply, and a `system` message
is a platform-generated note.
example: assistant
content:
anyOf:
- type: string
- type: 'null'
title: Content
description: >-
Text of the message. Empty on assistant turns whose work is carried
entirely by tool calls, and on internal diff messages.
example: I added a contact form to the home page.
file_urls:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: File Urls
description: URLs of the files attached to the message, or `null` if it has none.
example:
- https://example.com/mockup.png
hidden:
anyOf:
- type: boolean
- type: 'null'
title: Hidden
description: >-
Whether the message is internal and hidden from the chat in the app
editor.
example: false
checkpoint_id:
anyOf:
- type: string
- type: 'null'
title: Checkpoint Id
description: >-
ID of the
[checkpoint](/developers/references/app-management/get-started/concepts#checkpoints)
this message produced, or `null` if it produced none. Pass it as
`checkpoint_id` to [Deploy an app](/api-reference/deploy-an-app) to
deploy that version.
example: 6886b8d390dc7e2f4a2c91b3
tool_calls:
anyOf:
- items:
$ref: '#/components/schemas/ConversationToolCallSummary'
type: array
- type: 'null'
title: Tool Calls
description: >-
Tool calls the AI made on this message, or `null` on messages that
made none. A call with `status` set to `waiting_for_user_input` is
holding the turn open until it is answered.
usage:
anyOf:
- $ref: '#/components/schemas/MessageUsageSummary'
- type: 'null'
description: >-
Tokens and credits this message consumed, or `null` on messages that
consumed none.
metadata:
anyOf:
- $ref: '#/components/schemas/MessageMetadataSummary'
- type: 'null'
description: Who created the message and when.
type: object
title: ConversationMessageSummary
ConversationToolCallSummary:
properties:
id:
anyOf:
- type: string
- type: 'null'
title: Id
description: >-
ID of the tool call. Pass it as `tool_call_id` to [Submit tool-call
input](/api-reference/submit-tool-call-input) when `status` is
`waiting_for_user_input`.
example: toolu_01A9FJd3kP2mNqRs7VwXyZ4b
name:
anyOf:
- type: string
- type: 'null'
title: Name
description: Name of the tool the AI is calling.
example: create_file
status:
anyOf:
- type: string
enum:
- running
- success
- error
- stopped
- waiting_for_user_input
- type: 'null'
title: Status
description: >-
Where the tool call is. Either `running`, `success`, `error`,
`stopped`, or `waiting_for_user_input`. The last one means the turn
is paused until the call is answered.
example: waiting_for_user_input
requires_user_input:
anyOf:
- type: boolean
- type: 'null'
title: Requires User Input
description: >-
Whether this tool call has to be approved or rejected before the
turn can continue.
example: true
arguments_string:
anyOf:
- type: string
- type: 'null'
title: Arguments String
description: >-
What the AI asked the tool to do, as a JSON object encoded in a
string. Parse it to see the arguments before answering a call that
is waiting. On a call whose `requires_user_input` is `true` the
value is complete rather than shortened, which is the case that
matters, because approving without reading it is approving blind. On
any other call it can be cut to the first 500 characters. The one
exception either way is the browser-typing tools,
`local_browser_type` and `local_browser_press_key`, which always
replace what was typed with `[redacted]` so a password or one-time
code is never returned, waiting or not. Approving one of those means
approving a value you cannot see. It is an empty string on a tool
call that takes no arguments.
example: >-
{"file_path": "src/pages/Home.jsx", "content": "export default
function Home() {}"}
type: object
title: ConversationToolCallSummary
description: A tool call on an assistant message.
MessageUsageSummary:
properties:
prompt_tokens:
anyOf:
- type: integer
- type: 'null'
title: Prompt Tokens
description: >-
Tokens the model read for this message, including the conversation
history it was given.
example: 18432
completion_tokens:
anyOf:
- type: integer
- type: 'null'
title: Completion Tokens
description: Tokens the model generated for this message.
example: 742
credits_charged:
anyOf:
- type: number
- type: 'null'
title: Credits Charged
description: Credits charged for this message, or `null` if it was not billed.
example: 1.5
type: object
title: MessageUsageSummary
MessageMetadataSummary:
properties:
created_date:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Created Date
description: Time the message was created, as a UTC timestamp in ISO 8601 format.
example: '2026-08-02T14:30:00'
created_by_email:
anyOf:
- type: string
- type: 'null'
title: Created By Email
description: >-
Email of the user whose turn produced the message, or `anonymous` on
a message Base44 created with no user in context.
example: developer@example.com
type: object
title: MessageMetadataSummary
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: api_key
description: Personal API key.
````