> ## 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.
# Send chat message
> This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.
Sends a message to the app's AI chat and runs the [turn](/developers/references/app-management/get-started/concepts#turns) it starts. Each turn consumes credits. This is how you build an app after creating it.
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 run a second time and charged again.
The request stays open until the AI finishes the whole turn, so it can take several minutes on a large change. The response is the app once the turn settles, with the messages the turn produced under `conversation.messages`. That list is ordered oldest first, so the AI's reply is the last entry whose `role` is `assistant`.
A `200` response does not mean the turn succeeded, and it does not always describe a turn. Three cases come back as a `200`.
- **The turn ran and finished.** `status.state` is `ready` and the app is idle again.
- **The turn ran and failed.** `status.state` is `error`, and `status.error_source` says where it failed. A value of `paywall` means the app's workspace has no credits left and no work was done.
- **The message was queued.** The AI was already busy with an earlier message, so the response is `{"queued": true}` with the queue's state and none of the fields below. Check for `queued` before you read anything else.
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/message
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/message:
post:
summary: Send chat message
description: >-
This API is in beta. Endpoints, fields, and behavior may still
change, so avoid depending on it in production.
Sends a message to the app's AI chat and runs the
[turn](/developers/references/app-management/get-started/concepts#turns)
it starts. Each turn consumes credits. This is how you build an app
after creating it.
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 run a second time and
charged again.
The request stays open until the AI finishes the whole turn, so it can
take several minutes on a large change. The response is the app once the
turn settles, with the messages the turn produced under
`conversation.messages`. That list is ordered oldest first, so the AI's
reply is the last entry whose `role` is `assistant`.
A `200` response does not mean the turn succeeded, and it does not
always describe a turn. Three cases come back as a `200`.
- **The turn ran and finished.** `status.state` is `ready` and the app
is idle again.
- **The turn ran and failed.** `status.state` is `error`, and
`status.error_source` says where it failed. A value of `paywall` means
the app's workspace has no credits left and no work was done.
- **The message was queued.** The AI was already busy with an earlier
message, so the response is `{"queued": true}` with the queue's state
and none of the fields below. Check for `queued` before you read
anything else.
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: add_message_api_api_apps__app_id__chat_message_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: SendChatMessage
required:
- content
properties:
content:
type: string
description: What you want the AI to do. Up to 100,000 characters.
example: Add a contact form to the home page
file_urls:
type: array
items:
type: string
description: >-
Publicly reachable URLs of files to attach to the message,
such as a screenshot or a mockup for the AI to work from.
Base44 downloads each file, so a URL has to resolve without
credentials.
example:
- https://example.com/mockup.png
example:
content: Add a contact form to the home page
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ChatTurnResponse'
'400':
description: >-
The `content` field is longer than 100,000 characters, or a URL in
`file_urls` was rejected.
'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 new messages.
'422':
description: >-
The request body is missing `content`, or one of its fields has the
wrong type.
'503':
description: >-
The server is shutting down or the app's queue is unavailable. Retry
the request.
components:
schemas:
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.
````