> ## 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)

> <Info>This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.</Info>

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, unless the answers are kept for a turn that is still running (below). Resuming a turn consumes credits.

Set an `Idempotency-Key` or `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. Three 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 answers were kept for a turn that is still running.** Only with `nonblocking_cards`. The request returns right away, `app.status.state` is still `processing`, and every entry in `results` succeeds, meaning its answer was kept, not yet applied. The running turn applies the answers, or they resume it once it ends. If that turn is stopped or fails first, they are dropped and the tool calls wait for an answer again.

<Warning>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.</Warning>



## 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:
  - PersonalAccessTokenAuth: []
paths:
  /api/apps/{app_id}/chat/submit-tool-call-input/batch:
    post:
      summary: Submit tool-call input (batch)
      description: >-
        <Info>This API is in beta. Endpoints, fields, and behavior may still
        change, so avoid depending on it in production.</Info>


        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, unless the answers are kept for a turn that is still
        running (below). Resuming a turn consumes credits.


        Set an `Idempotency-Key` or `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. Three 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 answers were kept for a turn that is still running.** Only with
        `nonblocking_cards`. The request returns right away, `app.status.state`
        is still `processing`, and every entry in `results` succeeds, meaning
        its answer was kept, not yet applied. The running turn applies the
        answers, or they resume it once it ends. If that turn is stopped or
        fails first, they are dropped and the tool calls wait for an answer
        again.


        <Warning>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.</Warning>
      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
        - name: branch_id
          in: query
          required: false
          schema:
            type: string
            description: >-
              ID of the branch to work on, as returned by [List
              branches](/api-reference/list-branches). Omit it to work on the
              app's main branch.
            title: Branch Id
          description: >-
            ID of the branch to work on, as returned by [List
            branches](/api-reference/list-branches). Omit it to work on the
            app's main branch.
          example: 68f1a2b3c4d5e6f708192a3b
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            type: string
            description: >-
              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`.
            title: Idempotency-Key
          description: >-
            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`.
          example: 5d0e2a9c-6f1b-4c3e-8a7d-2b9f0c1e4a6d
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchToolCallInput'
      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, or no branch you can see has this `branch_id`.
        '409':
          description: >-
            The app or branch is busy with another operation that blocks this
            resume. On a branch, `extra_data.reason` is `branch_scope_read_only`
            when it was merged, or `branch_sync_in_progress` while it's being
            updated from main and the message can't be queued. Otherwise a
            message sent during an update is queued and runs after it, or
            answers the AI's question while the update waits on one and the tool
            call isn't the update's own question.
        '413':
          description: >-
            `function_source_too_large`: the function's source (its file paths
            and contents together) is over the 12 MiB per-function storage cap,
            so its source wasn't stored. The function may already be deployed,
            and on a file save the file itself may already be written to the
            app. `details` carries `function_name`, `size_bytes` and
            `limit_bytes`. Make the function smaller, for example by moving
            large data out of its code.
          content:
            application/json:
              examples:
                function_source_too_large:
                  summary: function_source_too_large
                  value:
                    error:
                      code: function_source_too_large
                      message: >-
                        Backend function 'export' source is 18084640 bytes —
                        exceeds the 12582912-byte per-function storage cap
                      details:
                        function_name: export
                        size_bytes: 18084640
                        limit_bytes: 12582912
              schema:
                $ref: '#/components/schemas/StandardErrorEnvelope'
        '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: >-
            Database temporarily unavailable (`database_unavailable`): the data
            cluster did not answer in time. Retry after the `Retry-After`
            seconds.
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorEnvelope'
              examples:
                database_unavailable:
                  summary: database_unavailable
                  value:
                    error:
                      code: database_unavailable
                      message: Database temporarily unavailable, please retry
                      details: {}
      security:
        - PersonalAccessTokenAuth:
            - full_access
        - WorkspaceApiKeyAuth:
            - full_access
        - WorkspaceApiKeyBearerAuth:
            - full_access
components:
  schemas:
    BatchToolCallInput:
      properties:
        tool_call_ids:
          items:
            type: string
          type: array
          maxItems: 100
          title: Tool Call Ids
          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
          title: Action
          description: Whether to let these tool calls run or turn them down.
          example: approved
        extra_user_input:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Extra User Input
          description: >-
            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.
        nonblocking_cards:
          type: boolean
          title: Nonblocking Cards
          description: >-
            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.
          default: false
      type: object
      required:
        - tool_call_ids
        - action
      title: BatchToolCallInput
      example:
        action: approved
        tool_call_ids:
          - toolu_01A9FJd3kP2mNqRs7VwXyZ4b
    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.
    StandardErrorEnvelope:
      properties:
        error:
          $ref: '#/components/schemas/StandardError'
          description: What went wrong.
      type: object
      required:
        - error
      title: StandardErrorEnvelope
      description: The error body returned in the standard envelope.
    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/StatusObject'
            - 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.
    StandardError:
      properties:
        code:
          type: string
          title: Code
          description: >-
            Stable machine-readable cause of the failure. Match on this, not on
            `message`.
          example: not_found
        message:
          type: string
          title: Message
          description: Human-readable explanation. It isn't a stable contract.
          example: App not found
        details:
          additionalProperties: true
          type: object
          title: Details
          description: >-
            Structured context for the failure, or an empty object when there's
            none.
          example: {}
      type: object
      required:
        - code
        - message
      title: StandardError
    StatusObject:
      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/PaywallStatusContext'
            - 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: StatusObject
      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
    PaywallStatusContext:
      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: PaywallStatusContext
    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:
    PersonalAccessTokenAuth:
      type: http
      scheme: bearer
      description: >-
        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`.
    WorkspaceApiKeyAuth:
      type: apiKey
      in: header
      name: api_key
      description: >-
        Workspace API key, sent as `api_key: <key>`. Each operation that accepts
        one lists what the key needs: a permission, `read_only` or
        `full_access`, like a personal access token, or a scope. A key without
        the scope gets 403 `workspace_api_key_scope_required`.
    WorkspaceApiKeyBearerAuth:
      type: http
      scheme: bearer
      description: >-
        Workspace API key, sent as `Authorization: Bearer <key>`. Accepted
        wherever `api_key` is, with the same permission.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.