Sign in

Send chat message

<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 builder and runs the turn it starts. This is how you build an app after creating it.

The request stays open until the builder 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 it produced under conversation.messages. Read the newest assistant message for the builder's reply, and status.state to see how the turn ended. Each turn consumes credits.

<Warning>A turn that fails still returns 200. Check status.state: error means the turn failed, and status.error_source says where. paywall there means you ran out of credits and no work was done.</Warning>

<Note>If the builder is already busy with an earlier message, this app may queue yours instead of running it now. The response is then {"queued": true} with the queue's state, and it carries none of the fields below. Check for queued before reading the app.</Note>

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

post/api/apps/{app_id}/chat/message

Path parameters

app_idstring required

ID of the app whose builder chat this request acts on.

ID of the app whose builder chat this request acts on.

Request body

contentstring required

What you want the AI builder to do. Up to 100,000 characters.

file_urlsstring[]

URLs of files to attach to the message, such as a screenshot or a mockup for the builder to work from.

Example request

{
  "content": "Add a contact form to the home page",
  "file_urls": [
    "https://storage.base44.com/uploads/mockup.png"
  ]
}

Response

The app once the turn finished, or the queue state if the message was queued.

idstring nullable

ID of the app.

namestring nullable

Display name of the app.

Example response

{
  "id": "6820f3a4e7b91d003c45a1f2",
  "name": "My CRM",
  "status": {
    "state": "ready",
    "details": "Publishing app",
    "request_id": "a1b2c3d4e5f67890abcdef12",
    "last_updated_date": "2026-08-02T14:30:00",
    "error_source": "build",
    "paywall_context": {
      "billing_organization_id": "6820f3a4e7b91d003c45a1f2",
      "user_id": "6820f3a4e7b91d003c45a1f3",
      "evaluated_at": "2026-08-02T14:30:00"
    }
  },
  "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://storage.base44.com/uploads/mockup.png"
        ],
        "checkpoint_id": "6886b8d390dc7e2f4a2c91b3",
        "tool_calls": [
          {
            "id": "toolu_01A9FJd3kP2mNqRs7VwXyZ4b",
            "name": "create_file",
            "status": "waiting_for_user_input",
            "requires_user_input": true
          }
        ],
        "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"
        }
      }
    ]
  }
}

Changes