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

Sends a message to the app's AI chat and runs the turn it starts. Each turn consumes credits. This is how you build an app after creating it.

Set an Idempotency-Key or X-Request-ID header before you send. A network retry 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.

Set branch_id to send the message to a branch instead of main. The turn changes only that branch, and the response carries the branch's messages and the turn's status. Each branch has its own queue, so pass the same branch_id to the queue endpoints to manage it. A retry that Base44 ignores returns main's status rather than the branch's, so read the branch turn's state from run_state in Get branch.

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. Track queued messages with Get message queue. On an app that queues messages, every message you send while the queue is paused is queued until you call Resume message queue.

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

{
  "content": "Add a contact form to the home page"
}

{
  "id": "6820f3a4e7b91d003c45a1f2",
  "name": "My CRM",
  "status": {
    "state": "ready",
    "details": "Publishing app",
    "request_id": "a1b2c3d4e5f67890abcdef12",
    "last_updated_date": "2026-08-02T14:30:00Z",
    "error_source": "build",
    "paywall_context": {
      "billing_organization_id": "67e0b12c4d8a3f005b21c9e4",
      "user_id": "6706af53b9c1e2004a37d85f",
      "evaluated_at": "2026-08-02T14:30:00Z"
    }
  },
  "conversation": {
    "id": "1f0c2b7a-9d51-4c3e-8a62-7b4d5e6f8a90",
    "messages": [
      {
        "id": "7f3a1c88-52d4-4a0e-9b31-2c6f0d8e4a19",
        "role": "assistant",
        "content": "I added a contact form to the home page.",
        "file_urls": [
          "https://example.com/mockup.png"
        ],
        "checkpoint_id": "6886b8d390dc7e2f4a2c91b3",
        "tool_calls": [
          {
            "id": "toolu_01A9FJd3kP2mNqRs7VwXyZ4b",
            "name": "create_file",
            "status": "waiting_for_user_input",
            "requires_user_input": true,
            "arguments_string": "{\"file_path\": \"src/pages/Home.jsx\", \"content\": \"export default function Home() {}\"}"
          }
        ],
        "usage": {
          "prompt_tokens": 18432,
          "completion_tokens": 742,
          "credits_charged": 1.5
        },
        "metadata": {
          "created_date": "2026-08-02T14:30:00",
          "created_by_email": "developer@example.com"
        }
      }
    ]
  }
}