---
title: "Merge branch"
method: POST
path: "/api/apps/{app_id}/branches/{branch_id}/merge"
---

# Merge branch

`POST /api/apps/{app_id}/branches/{branch_id}/merge`

## Request

- Base URL: `https://app.base44.com`
- URL: `https://app.base44.com/api/apps/{app_id}/branches/{branch_id}/merge`
- Auth: HTTP bearer

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

Merges an active branch into the app's main branch. Base44 merges the branch's code into main, applies its entity and backend function changes to main, saves a checkpoint, and adds a message to main's conversation that summarizes the merge. The branch's `status` then becomes `merged`, and it can't be changed after that. Comments left on the branch's preview are deleted. This works while [main branch protection](/api-reference/set-main-branch-protection) is on.

The request returns once the merge is done. A 409 leaves the branch active and main unchanged. Its `extra_data.reason` tells you what to do:

- `branch_has_no_changes`: the branch has no code changes to merge.
- `branch_merge_conflict`: the branch conflicts with main. [Update the branch from main](/api-reference/update-branch-from-main) to resolve the conflicts, then merge again.
- `app_processing` or `branch_processing`: the AI is working on main or on the branch. Try again once it's done.
- `branch_sync_in_progress`: the branch is being updated from main. Try again once [Get branch sync status](/api-reference/get-branch-sync-status) shows `sync_state` as `idle`.
- `branch_pending_commit_wait_failed`: the branch's latest changes are still being saved. Try again shortly.

In this response, `branch.created_by_name` is always `null`. [Get branch](/api-reference/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](/api-reference/send-chat-message). Until it has some, merging it returns a 409 with `branch_has_no_changes`.</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.</Warning>

## Path parameters

- `branch_id` string, required: ID of the branch, as returned by [List branches](/api-reference/list-branches).
- `app_id` string, required: ID of the app the branch belongs to.

## Response `200`

The merged branch.

- MergedBranch: The merged branch.
  - `branch` BranchSummary, required: A branch of an app.
    - `id` string, required: ID of the branch.
    - `app_id` string, required: ID of the app the branch belongs to.
    - `branch_name` string, 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.
    - `run_state` BranchRunState, required
      - `state` 'ready' | 'processing' | 'error', required: `processing` while the AI is working on the branch, `ready` once it's idle, and `error` when the last turn on the branch failed.
      - `details` string, nullable, required: Short note about the state, such as why the last turn failed, or `null` when there's nothing to report.
      - `last_updated_date` string, date-time, required: When the state last changed, as a UTC timestamp in ISO 8601 format.
    - `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_id` string, nullable, required: ID of the main [checkpoint](/api-reference/list-checkpoints) the branch started from, or `null` if the app had no checkpoint yet.
    - `created_by_id` string, required: ID of the user who created the branch.
    - `created_by_name` string, 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_date` string, date-time, required: When the branch was created, as a UTC timestamp in ISO 8601 format.
    - `merged_at` string, 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_id` string, 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_url` string, required: URL of the branch's preview. It shows the branch only while it's active and once it has been built.
  - `merge_message_id` string, required: ID of the message Base44 added to main's conversation to summarize the merge. Find it with [Read conversation messages](/api-reference/read-conversation-messages).

## Other responses

- `400`: The branch isn't active: it was already merged or deleted.
- `401`: Missing or invalid credentials.
- `403`: You don't have editor access to this app, the app is blocked, your API key is read-only, or you used a workspace API key.
- `404`: App not found, or the app has no branch with this ID.
- `409`: The branch has no changes to merge, conflicts with main, or is busy. `extra_data.reason` says which.
- `429`: Rate limit exceeded. The base limit is 30 requests per minute. See [Rate limits](/developers/references/apps-api/get-started/rate-limits) for the multiplier your plan gets.

## Changes

> 58 revisions in range; 1 not diffed.

- **2026-10-12** `5e139db2e643`: 1 info
  - the endpoint scheme security `PersonalAccessTokenAuth` was added to the API
- **2026-10-09** `7843e6425fe2`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/adexad/apis/base44-app-management-api/changes/api/apps/:app_id/branches/:branch_id/merge/post.md)

---

[API](https://skmtc.dev/adexad/apis/base44-app-management-api.md) · [All operations](https://skmtc.dev/adexad/apis/base44-app-management-api/llms.txt) · [OpenAPI document](https://skmtc.dev/adexad/apis/base44-app-management-api/revisions/fa29e915c226?raw)