> ## Documentation Index
> Fetch the complete documentation index at: https://docs.base44.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create branch

> Creates a [branch](/developers/references/app-management/get-started/concepts#branches) 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](/api-reference/merge-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](/api-reference/get-branch) returns it.

This endpoint is limited to 30 requests per minute, shared with Create branch, Delete branch, Merge branch and Import repository 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, [Merge branch](/api-reference/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, or a workspace API key, which acts as the workspace owner. A read-only key is refused.</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>



## OpenAPI

````yaml /developers/references/app-management/app-management-openapi.json post /api/apps/{app_id}/branches
openapi: 3.1.0
info:
  title: Base44 App Management API
  version: 1.0.0
servers:
  - url: https://app.base44.com
security:
  - PersonalAccessTokenAuth: []
paths:
  /api/apps/{app_id}/branches:
    post:
      summary: Create branch
      description: >-
        Creates a
        [branch](/developers/references/app-management/get-started/concepts#branches)
        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](/api-reference/merge-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](/api-reference/get-branch) returns it.


        This endpoint is limited to 30 requests per minute, shared with Create
        branch, Delete branch, Merge branch and Import repository 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, [Merge
        branch](/api-reference/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, or a workspace API key, which acts as the
        workspace owner. A read-only key is refused.</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>
      operationId: create_branch_api_apps__app_id__branches_post
      parameters:
        - name: app_id
          in: path
          required: true
          schema:
            type: string
            description: ID of the app to create the branch in.
            title: App Id
          description: ID of the app to create the branch in.
          example: 6820f3a4e7b91d003c45a1f2
        - name: branch_id
          in: query
          required: false
          schema:
            type: string
            description: >-
              ID of the branch to work on, as returned by [List
              branches](/api-reference/list-branches). Omit it to work on the
              app's main branch.
            title: Branch Id
          description: >-
            ID of the branch to work on, as returned by [List
            branches](/api-reference/list-branches). Omit it to work on the
            app's main branch.
          example: 68f1a2b3c4d5e6f708192a3b
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBranchRequest'
      responses:
        '200':
          description: The new branch.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BranchSummary'
        '400':
          description: >-
            `branch_name` is `main`, or you set `from_message_id` on an app
            imported from GitHub, or the message's saved version belongs to a
            branch rather than main.
        '401':
          description: Missing or invalid credentials.
        '403':
          description: >-
            You don't have editor access to this app, the app is blocked, or
            your API key is read-only. The code is `branches_not_supported` when
            the app's type doesn't support branches.
        '404':
          description: >-
            App not found, `from_message_id` isn't in main's conversation or has
            no saved version to start from, or no branch you can see has this
            `branch_id`.
        '409':
          description: >-
            An active or merged branch is already named `branch_name`, or you
            sent a `branch_id` (`extra_data.reason` is
            `create_branch_requires_main_scope`).
        '422':
          description: >-
            None of `branch_name`, `prompt`, and `from_message_id` is set,
            `branch_name` breaks the naming rules or is over 100 characters, or
            `from_message_id` is over 64 characters.
        '429':
          description: >-
            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.
        '503':
          description: >-
            Database temporarily unavailable (`database_unavailable`): the data
            cluster did not answer in time. Retry after the `Retry-After`
            seconds.
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorEnvelope'
              examples:
                database_unavailable:
                  summary: database_unavailable
                  value:
                    error:
                      code: database_unavailable
                      message: Database temporarily unavailable, please retry
                      details: {}
      security:
        - PersonalAccessTokenAuth:
            - full_access
        - WorkspaceApiKeyAuth:
            - full_access
        - WorkspaceApiKeyBearerAuth:
            - full_access
components:
  schemas:
    CreateBranchRequest:
      properties:
        branch_name:
          anyOf:
            - type: string
              maxLength: 100
              minLength: 1
            - type: 'null'
          title: Branch Name
          description: >-
            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`.
          example: add-contact-form
        prompt:
          anyOf:
            - type: string
            - type: 'null'
          title: Prompt
          description: >-
            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.
          example: Add a contact form to the home page
        from_message_id:
          anyOf:
            - type: string
              maxLength: 64
            - type: 'null'
          title: From Message Id
          description: >-
            ID of a message in main's conversation, from [Read conversation
            messages](/api-reference/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: 7f3a1c88-52d4-4a0e-9b31-2c6f0d8e4a19
        is_private:
          type: boolean
          title: Is Private
          description: >-
            Make the branch visible only to you. Other collaborators can't list,
            open or join it. Once merged, its changes appear on main as usual.
            Not available for apps imported from GitHub.
          default: false
          example: true
      type: object
      title: CreateBranchRequest
      description: The new branch's name, or text to name it from.
    BranchSummary:
      properties:
        id:
          type: string
          title: Id
          description: ID of the branch.
          example: 68f1a2b3c4d5e6f708192a3b
        app_id:
          type: string
          title: App Id
          description: ID of the app the branch belongs to.
          example: 6820f3a4e7b91d003c45a1f2
        branch_name:
          type: string
          title: Branch Name
          description: Name of the branch.
          example: add-contact-form
        status:
          type: string
          enum:
            - active
            - merged
            - deleted
          title: Status
          description: >-
            `active` while the branch can still be worked on, `merged` once it
            was merged into main, and `deleted` once it was deleted.
          example: active
        run_state:
          anyOf:
            - $ref: '#/components/schemas/BranchRunState'
            - type: 'null'
          description: >-
            State of the AI's work on the branch, or `null` if no turn has run
            on it yet.
        code_state:
          type: string
          enum:
            - unchanged
            - changed
          title: Code State
          description: >-
            `unchanged` when the branch has no code changes of its own to merge
            into main. `changed` otherwise, including when Base44 can't tell
            yet.
          example: changed
        base_checkpoint_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Base Checkpoint Id
          description: >-
            ID of the main [checkpoint](/api-reference/list-checkpoints) the
            branch started from, or `null` if the app had no checkpoint yet.
          example: 6886b8d390dc7e2f4a2c91b3
        session_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Session Id
          description: >-
            ID of the [session](/api-reference/get-session) this branch belongs
            to, or `null` for a branch Base44 hasn't put in a session yet.
          example: 6820f3a4e7b91d003c45a1f9
        created_by_id:
          type: string
          title: Created By Id
          description: ID of the user who created the branch.
          example: 68a0c1d2e3f4a5b6c7d8e9f0
        created_by_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Created By Name
          description: >-
            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.
          example: Jane Doe
        created_date:
          type: string
          format: date-time
          title: Created Date
          description: When the branch was created, as a UTC timestamp in ISO 8601 format.
          example: '2026-09-28T10:15:00'
        merged_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Merged At
          description: >-
            When the branch was merged into main, as a UTC timestamp in ISO 8601
            format, or `null` if it wasn't.
          example: '2026-09-29T08:02:11'
        merged_by_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Merged By Id
          description: >-
            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.
          example: 68a0c1d2e3f4a5b6c7d8e9f0
        static_preview_url:
          type: string
          title: Static Preview Url
          description: >-
            URL of the branch's preview. It shows the branch only while it's
            active and once it has been built.
          example: https://preview--6820f3a4e7b91d003c45a1f2--b-d8c647b.base44.app
      type: object
      required:
        - id
        - app_id
        - branch_name
        - status
        - run_state
        - code_state
        - base_checkpoint_id
        - session_id
        - created_by_id
        - created_by_name
        - created_date
        - merged_at
        - merged_by_id
        - static_preview_url
      title: BranchSummary
      description: A branch of an app.
    StandardErrorEnvelope:
      properties:
        error:
          $ref: '#/components/schemas/StandardError'
          description: What went wrong.
      type: object
      required:
        - error
      title: StandardErrorEnvelope
      description: The error body returned in the standard envelope.
    BranchRunState:
      properties:
        state:
          type: string
          enum:
            - ready
            - processing
            - error
          title: State
          description: >-
            `processing` while the AI is working on the branch, `ready` once
            it's idle, and `error` when the last turn on the branch failed.
          example: ready
        details:
          anyOf:
            - type: string
            - type: 'null'
          title: Details
          description: >-
            Short note about the state, such as why the last turn failed, or
            `null` when there's nothing to report.
          example: Restoring checkpoint
        last_updated_date:
          type: string
          format: date-time
          title: Last Updated Date
          description: When the state last changed, as a UTC timestamp in ISO 8601 format.
          example: '2026-09-28T10:18:40'
      type: object
      required:
        - state
        - details
        - last_updated_date
      title: BranchRunState
    StandardError:
      properties:
        code:
          type: string
          title: Code
          description: >-
            Stable machine-readable cause of the failure. Match on this, not on
            `message`.
          example: not_found
        message:
          type: string
          title: Message
          description: Human-readable explanation. It isn't a stable contract.
          example: App not found
        details:
          additionalProperties: true
          type: object
          title: Details
          description: >-
            Structured context for the failure, or an empty object when there's
            none.
          example: {}
      type: object
      required:
        - code
        - message
      title: StandardError
  securitySchemes:
    PersonalAccessTokenAuth:
      type: http
      scheme: bearer
      description: >-
        Personal access token, sent as `Authorization: Bearer <token>`. Each
        operation lists the permission it needs: `read_only` or `full_access`. A
        full-access token can call every operation. A read-only token can call
        only the operations that list `read_only`; anything else returns 403
        `read_only_credential_route_not_allowed`.
    WorkspaceApiKeyAuth:
      type: apiKey
      in: header
      name: api_key
      description: >-
        Workspace API key, sent as `api_key: <key>`. Each operation that accepts
        one lists what the key needs: a permission, `read_only` or
        `full_access`, like a personal access token, or a scope. A key without
        the scope gets 403 `workspace_api_key_scope_required`.
    WorkspaceApiKeyBearerAuth:
      type: http
      scheme: bearer
      description: >-
        Workspace API key, sent as `Authorization: Bearer <key>`. Accepted
        wherever `api_key` is, with the same permission.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.