> ## 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 a sandbox checkpoint

> Saves the app's current state as a checkpoint you can return to.

Every sandbox-bridge endpoint runs against the app's live sandbox, the same filesystem the AI edits, so a change here is visible in the app editor immediately.

This is what makes sandbox work restorable. Writes through this API are committed to git but not checkpointed, and only checkpoints appear in the app editor's version history: a Restore or Revert there rolls the app back to the last checkpoint and discards everything written after it. Take a checkpoint when you finish a unit of work and always before you stop, and one before a risky batch of edits so a bad change is one restore away. Pending writes are flushed first, so the checkpoint captures the sandbox as it stands.

Restore it with [Restore checkpoint](/api-reference/restore-checkpoint), and list what an app has with [List checkpoints](/api-reference/list-checkpoints). Checkpoints created here show up alongside the ones the AI takes.

This endpoint is limited to 60 requests per minute per app, shared with the other sandbox-bridge endpoints that change files.

<Note>The bridge needs a Builder plan or higher on the app's workspace, and answers 402 below that (`PREMIUM_REQUIRED`). Where sandbox calls are metered, each call is charged to the app's integration credits and a workspace that has none left answers 402 with `CREDITS_EXHAUSTED`. The bridge is unavailable for agent apps. A personal API key works as-is, and so does a workspace API key, which acts as the workspace owner. An OAuth access token needs the `sandbox:write` scope.</Note>

<Tip>Every error response carries a stable `extra_data.code` alongside the human-readable `message`. Branch on the code rather than on the message text or the status.</Tip>



## OpenAPI

````yaml /developers/references/app-management/app-management-openapi.json post /api/apps/{app_id}/sandbox-bridge/create_checkpoint
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}/sandbox-bridge/create_checkpoint:
    post:
      summary: Create a sandbox checkpoint
      description: >-
        Saves the app's current state as a checkpoint you can return to.


        Every sandbox-bridge endpoint runs against the app's live sandbox, the
        same filesystem the AI edits, so a change here is visible in the app
        editor immediately.


        This is what makes sandbox work restorable. Writes through this API are
        committed to git but not checkpointed, and only checkpoints appear in
        the app editor's version history: a Restore or Revert there rolls the
        app back to the last checkpoint and discards everything written after
        it. Take a checkpoint when you finish a unit of work and always before
        you stop, and one before a risky batch of edits so a bad change is one
        restore away. Pending writes are flushed first, so the checkpoint
        captures the sandbox as it stands.


        Restore it with [Restore checkpoint](/api-reference/restore-checkpoint),
        and list what an app has with [List
        checkpoints](/api-reference/list-checkpoints). Checkpoints created here
        show up alongside the ones the AI takes.


        This endpoint is limited to 60 requests per minute per app, shared with
        the other sandbox-bridge endpoints that change files.


        <Note>The bridge needs a Builder plan or higher on the app's workspace,
        and answers 402 below that (`PREMIUM_REQUIRED`). Where sandbox calls are
        metered, each call is charged to the app's integration credits and a
        workspace that has none left answers 402 with `CREDITS_EXHAUSTED`. The
        bridge is unavailable for agent apps. A personal API key works as-is,
        and so does a workspace API key, which acts as the workspace owner. An
        OAuth access token needs the `sandbox:write` scope.</Note>


        <Tip>Every error response carries a stable `extra_data.code` alongside
        the human-readable `message`. Branch on the code rather than on the
        message text or the status.</Tip>
      operationId: >-
        create_checkpoint_endpoint_api_apps__app_id__sandbox_bridge_create_checkpoint_post
      parameters:
        - name: app_id
          in: path
          required: true
          schema:
            type: string
            description: ID of the app whose sandbox to operate on.
            title: App Id
          description: ID of the app whose sandbox to operate on.
          example: 6820f3a4e7b91d003c45a1f2
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              default: {}
              title: CreateSandboxCheckpoint
              properties:
                branch_id:
                  anyOf:
                    - type: string
                    - type: 'null'
                  description: Optional Base44 branch ID. Omit to operate on main.
                  title: Branch Id
                name:
                  anyOf:
                    - maxLength: 200
                      type: string
                    - type: 'null'
                  description: >-
                    Optional message/title for the checkpoint. Defaults to an
                    auto-generated title.
                  title: Name
              required: []
            example:
              name: Before refactoring the dashboard
        required: true
      responses:
        '200':
          description: The checkpoint that was created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateCheckpointResult'
        '401':
          description: Missing or invalid credentials.
        '402':
          description: The app's workspace plan doesn't include the sandbox bridge.
        '403':
          description: >-
            You don't have access to this app, the app is blocked, or your OAuth
            token is missing the scope this endpoint needs.
        '404':
          description: App not found.
        '409':
          description: >-
            The app is on a branch that can't be written to, or an earlier
            change is still being committed. Also answered with
            `UNMANAGED_SOURCE_CODE` when the app's source code is managed
            outside Base44, for example with the Base44 CLI.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Rate limit exceeded (60 requests per minute).
        '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:
    CreateCheckpointResult:
      properties:
        checkpoint_id:
          type: string
          title: Checkpoint Id
          description: >-
            ID of the checkpoint. Pass it as `checkpoint_id` to [Restore
            checkpoint](/api-reference/restore-checkpoint) to come back to this
            state.
          example: 6886b8d390dc7e2f4a2c91b3
        name:
          type: string
          title: Name
          description: >-
            The checkpoint's title, either the `name` you sent or one Base44
            generated.
          example: Before refactoring the dashboard
        git_commit_hash:
          anyOf:
            - type: string
            - type: 'null'
          title: Git Commit Hash
          description: >-
            The commit this checkpoint points at, or `null` when the app has no
            committed sandbox revision yet. A checkpoint without one still
            restores the app state Base44 captured.
          example: 4f9c1a7e8b2d3c5f6a0b1e2d3c4f5a6b7c8d9e0f
      type: object
      required:
        - checkpoint_id
        - name
      title: CreateCheckpointResult
      description: The checkpoint that was created.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    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.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    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.