BAbase44

Create branch

Changed on

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

Creates a branch of the app from its main branch. The branch has its own copy of the app's code, so its changes don't reach main until you merge the branch.

Set branch_name to name the branch, or send prompt and Base44 generates a short name from it. prompt only names the branch. It isn't sent to the AI. When a generated name is taken, Base44 adds a number to it. A branch_name you choose must not belong to another active or merged branch.

The branch starts from main's latest saved state. If the AI is working on main at the time, the branch starts from main as it was before that change. Set from_message_id to start from an earlier point instead. Send at least one of branch_name, prompt, and from_message_id.

Branches are created from main only. Sending a branch_id returns a 409 with extra_data.reason set to create_branch_requires_main_scope.

In this response, created_by_name is always null. Get branch returns it.

This endpoint is limited to 30 requests per minute, shared with Create branch, Delete branch and Merge branch.

<Note>A branch gets changes of its own from chat messages sent to it: pass the branch's id as branch_id to Send chat message. Until it has some, Merge branch refuses it with a 409.</Note>

<Note>This endpoint accepts a personal API key belonging to a user with editor access to the app. A read-only key is refused, and workspace API keys are not accepted.</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}/branches

Request

  • Base URL
    https://app.base44.com
  • URL
    https://app.base44.com/api/apps/{app_id}/branches
  • Auth
    HTTP bearer

Path parameters

app_idstring required

ID of the app to create the branch in.

Query parameters

branch_idstring

ID of the branch to work on, as returned by List branches. Omit it to work on the app's main branch.

Request body

branch_namestring nullable

Name of the branch. It starts with a letter or digit and contains only letters, digits, ., _, / and -. It can't contain .. or //, end with / or ., start with b44/, or be main, and no part between slashes can start with . or end with .lock. Leave it out to have Base44 name the branch from prompt.

promptstring nullable

Text to name the branch from when you leave out branch_name. Base44 generates a short name from it. An empty string names the branch after your first name and today's date.

from_message_idstring nullable

ID of a message in main's conversation, from Read conversation messages. The branch starts from the app as it was when that message was sent, instead of from main's latest state. Without branch_name, the branch is named after the last user message before that one, and prompt is ignored.

Example request

{
  "branch_name": "add-contact-form",
  "prompt": "Add a contact form to the home page",
  "from_message_id": "7f3a1c88-52d4-4a0e-9b31-2c6f0d8e4a19"
}

Response

The new branch.

idstring required

ID of the branch.

app_idstring required

ID of the app the branch belongs to.

branch_namestring required

Name of the branch.

status'active' | 'merged' | 'deleted' required

active while the branch can still be worked on, merged once it was merged into main, and deleted once it was deleted.

code_state'unchanged' | 'changed' required

unchanged when the branch has no code changes of its own to merge into main. changed otherwise, including when Base44 can't tell yet.

base_checkpoint_idstring nullable required

ID of the main checkpoint the branch started from, or null if the app had no checkpoint yet.

session_idstring nullable required

ID of the session this branch belongs to, or null for a branch Base44 hasn't put in a session yet.

created_by_idstring required

ID of the user who created the branch.

created_by_namestring nullable required

Display name of the user who created the branch, or the part of their email before the @ when they have no name. null when Base44 can't name them, for example when their account no longer exists.

created_datestring date-time required

When the branch was created, as a UTC timestamp in ISO 8601 format.

merged_atstring date-time nullable required

When the branch was merged into main, as a UTC timestamp in ISO 8601 format, or null if it wasn't.

merged_by_idstring nullable required

ID of the user who merged the branch, or null if it wasn't merged or Base44 doesn't know who did, as for a branch whose pull request was merged on GitHub.

static_preview_urlstring required

URL of the branch's preview. It shows the branch only while it's active and once it has been built.

Example response

{
  "id": "68f1a2b3c4d5e6f708192a3b",
  "app_id": "6820f3a4e7b91d003c45a1f2",
  "branch_name": "add-contact-form",
  "status": "active",
  "run_state": {
    "state": "ready",
    "details": "Restoring checkpoint",
    "last_updated_date": "2026-09-28T10:18:40"
  },
  "code_state": "changed",
  "base_checkpoint_id": "6886b8d390dc7e2f4a2c91b3",
  "session_id": "6820f3a4e7b91d003c45a1f9",
  "created_by_id": "68a0c1d2e3f4a5b6c7d8e9f0",
  "created_by_name": "Jane Doe",
  "created_date": "2026-09-28T10:15:00",
  "merged_at": "2026-09-29T08:02:11",
  "merged_by_id": "68a0c1d2e3f4a5b6c7d8e9f0",
  "static_preview_url": "https://preview--6820f3a4e7b91d003c45a1f2--b-d8c647b.base44.app"
}

Changes