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 chat and runs the turn 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 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.

<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",
  "file_urls": [
    "https://example.com/mockup.png"
  ]
}

{
  "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"
        }
      }
    ]
  }
}