Skip to main content
A build turn is the loop your product wraps. A builder describes what they want, and the Base44 agent builds it, pausing occasionally to ask a question, until an app is ready. These are the calls that loop is made of.
1

Create the app from a prompt

Call Create app to create the app and start building it from the specified prompt.Because the build starts inside this call, anything the build itself needs has to be in this request. That includes:
Updating an app uses a different call. Send each new prompt through Send chat message, with the app ID in the URL.
App creation is capped at 5 requests per minute. Queue bursts rather than firing them in parallel.If a field name doesn’t match what Create app accepts, whether from a typo or because it’s unsupported, the platform drops it with no error, and the create still succeeds. Read the field back from the created app afterward to confirm it applied.
2

Watch it build

Nothing is pushed to you. Poll Get app and read status.state, which is processing while the build runs, ready when it settles, and error when it failed.Read conversation messages gives you the transcript to render alongside it.
Size your timeouts for an LLM turn, not for CRUD. Create app, Send chat message, Submit tool-call input, and Deploy an app all wait on real work. A turn measures from around thirty seconds and can run to several minutes. A blanket 30-second client timeout aborts working builds and reports them as upstream failures. The reference integration allows 120 seconds for those four.The transcript carries every tool call’s arguments and results, file contents included, so it grows all build long. Page it rather than re-reading the whole thing.
3

Answer the agent's questions

A turn doesn’t always run to completion. The agent can stop, ask the builder a question, and wait indefinitely. Nothing else you send moves until it is answered.You find the question in the transcript, as a tool call whose status is waiting_for_user_input. It carries waiting_on.kind, and there are exactly three kinds. Build one UI for each, and you can handle every question the agent might ask.
4

Send the answer back

Submit tool-call input takes the tool call’s id and a decision, and resumes the turn. When the question wants content rather than a yes or no, use extra_user_input. If you approve, the agent receives it as the tool’s user_input.Send an X-Request-ID that stays the same across retries of the same submit. The reference integration derives it from the tool call’s id. Without a stable ID, a network-retried POST could resume the turn a second time and charge for it twice. With one, the server recognizes the retry and dedupes it.A few UI details matter here:
  • Declining is an answer. A rejection records the call as stopped, the tool never runs, and the agent carries on. Your UI needs an explicit decline button, not just an approve one.
  • Lock the message input while a question is open. If it isn’t locked the builder can attempt to send a message into a stopped turn and nothing happens.
When several questions are waiting and one decision answers all of them, use Submit tool-call input (batch).
5

Show the preview (optional)

Get preview URL returns a URL that serves the app as it currently stands, including unpublished changes, along with a separate preview_token needed to authenticate against it.Each app runs in its own sandbox, a live instance of its code that serves the preview. After a period of inactivity, the sandbox may require a cold start, so the first call can take noticeably longer. The response’s sandbox_info.cold_start field tells you whether that happened.
The preview_token is a credential with a short lifetime. Never cache it, and keep it out of logs.
6

Publish the app

Deploy an app is synchronous and has no review gate of its own, so any approval step your product needs is yours to build in front of it. By default the app’s current version goes live. To ship an earlier version, pass its id from List checkpoints as checkpoint_id. Every turn saves one of these versions. See Versions and rollback below.Get published URL returns the address of the deployed app. A 404 covers an app that was never published, one you unpublished, and one that does not exist, so read it as “nothing to link to yet” rather than as a diagnosis.

​
Versions and rollback

Base44 saves a checkpoint at the end of every build turn, and on imports, remixes, and manual saves. Publishing doesn’t save one. Base44’s own editor shows these checkpoints as a version history, and the same endpoints let your product do the same: list the versions, preview one in place, then restore it or publish it. To show a version history:
  1. Call List checkpoints, newest first, paged with limit and skip. Mark the row whose git_commit_hash matches the app’s last_git_commit_hash as the version your builder is on, and the one matching last_deployed_git_commit_hash as the live version. Both come from Get app.
  2. When a row’s preview_status is ready, show its preview_url where your product shows the app, with a way back to the live preview. It’s a static build, so it needs no sandbox and no preview token. While it’s pending or building, read the list again in a few seconds. When it’s failed, call Retry checkpoint build and poll the list until it settles.
  3. Do one of the following:
Restore checkpoint is what the editor’s restore button calls. The code rolls forward to that version as a new commit, so no history is lost, the backend functions are redeployed, the entity schemas are restored, and the chat is rewound to that point. Nothing is published, so say so in your confirmation.The call does all of that before it answers, so give it the timeout you give a build turn. The app’s status.state is processing for the duration, and if your request times out, poll Get app until it leaves processing instead of sending the restore again. It answers 409 while a turn is running, so disable restore while the app is processing. Afterwards, reload the conversation and the preview, because both changed.Undo message restores the checkpoint a message produced, and Edit and resend undoes back to a message and runs a new one in its place. Both restore a checkpoint underneath, so they share this behavior.
Deploy an app with { "checkpoint_id": "<id>" } makes production serve that version and leaves the builder’s draft untouched, which is how a production rollback ships without rewinding anyone’s work. An empty body publishes the current version. It answers 409 while the app is processing.
To save a named version after changing an app outside a turn, call Create checkpoint. When nothing changed since the latest version, it returns created: false with reason: no_changes.
These endpoints take a full-access personal access token. A read-only token and a workspace API key are refused. The reference integration’s version panel is in VersionHistoryPanel.jsx.

​
See also