> ## 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 app

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

Creates a new app. Pass `initial_message.content` to build it from a prompt, or send an empty body (`{}`) to create an empty app. Add `initial_message.file_urls` to build from a screenshot or a mockup alongside the prompt.

Building from a prompt runs in the background and consumes credits. Poll [Get app](/api-reference/get-app) and watch its `status` to see when the build finishes. By default the app is created in your default workspace. Set `organization_id` to create it in another workspace you belong to. This endpoint is limited to 5 requests per minute.

<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
openapi: 3.1.0
info:
  title: Base44 App Management API
  version: 1.0.0
servers:
  - url: https://app.base44.com
security:
  - ApiKeyAuth: []
paths:
  /api/apps:
    post:
      summary: Create app
      description: >-
        <Info>This API is in beta. Endpoints, fields, and behavior may still
        change, so avoid depending on it in production.</Info>


        Creates a new app. Pass `initial_message.content` to build it from a
        prompt, or send an empty body (`{}`) to create an empty app. Add
        `initial_message.file_urls` to build from a screenshot or a mockup
        alongside the prompt.


        Building from a prompt runs in the background and consumes credits. Poll
        [Get app](/api-reference/get-app) and watch its `status` to see when the
        build finishes. By default the app is created in your default workspace.
        Set `organization_id` to create it in another workspace you belong to.
        This endpoint is limited to 5 requests per minute.


        <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: api_create_api_apps_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
              title: CreateApp
              properties:
                initial_message:
                  type: object
                  description: >-
                    First prompt to build the app from. Omit to create an empty
                    app.
                  properties:
                    content:
                      type: string
                      description: Prompt describing the app to build.
                      example: A CRM to track leads and deals
                    file_urls:
                      type: array
                      items:
                        type: string
                      description: >-
                        Publicly reachable URLs of files to build the app from,
                        such as a screenshot or a mockup to copy the layout
                        from. Base44 downloads each file, so a URL has to
                        resolve without credentials. A URL Base44 cannot fetch
                        does not fail this request. The app is still created,
                        and the failure shows up afterwards as a `status.state`
                        of `error`.
                      example:
                        - https://example.com/mockup.png
                first_prompt_model_comparison:
                  type: object
                  description: >-
                    Build the first prompt with two eligible models and choose
                    one version.
                  required:
                    - models
                    - client_creation_id
                  properties:
                    models:
                      type: array
                      minItems: 2
                      maxItems: 2
                      items:
                        type: string
                    client_creation_id:
                      type: string
                      description: >-
                        Stable client-generated identifier used to resume this
                        creation request.
                organization_id:
                  type: string
                  description: >-
                    ID of the workspace to create the app in. Omit to use your
                    default workspace. You must have an editor-capable role
                    (Editor or above) in the workspace. Viewers and guests
                    cannot create apps. This is the same workspace ID that [List
                    apps](/api-reference/list-apps) accepts as `workspace_id`.
                  example: 67e0b12c4d8a3f005b21c9e4
            example:
              initial_message:
                content: A CRM to track leads and deals
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppSummary'
        '400':
          description: The request body is invalid.
        '401':
          description: Missing or invalid credentials.
        '403':
          description: >-
            You can't create apps in this workspace, because you are not a
            member or your role is not editor-capable.
        '422':
          description: The request body is missing, or is not a JSON object.
        '429':
          description: Rate limit exceeded (5 requests per minute).
components:
  schemas:
    AppSummary:
      properties:
        id:
          anyOf:
            - type: string
            - type: 'null'
          title: Id
          description: ID of the app.
          example: 6820f3a4e7b91d003c45a1f2
        first_prompt_model_comparison:
          anyOf:
            - $ref: '#/components/schemas/FirstPromptModelComparisonState'
            - type: 'null'
          description: >-
            Accepted first-prompt model comparison, including its durable
            comparison ID.
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
          description: Display name of the app.
          example: My CRM
        slug:
          anyOf:
            - type: string
            - type: 'null'
          title: Slug
          description: >-
            URL slug for the app, auto generated from the name and app ID or set
            to a custom value, or `null` if the app has no slug yet. The
            published URL is built from it.
          example: my-crm-3c45a1f2
        user_description:
          anyOf:
            - type: string
            - type: 'null'
          title: User Description
          description: >-
            Description of the app, or `null` if none was set. On a newly
            created app this holds the original prompt text.
          example: A CRM to track leads and deals
        created_by:
          anyOf:
            - type: string
            - type: 'null'
          title: Created By
          description: Email of the user who created the app.
          example: developer@example.com
        created_date:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Created Date
          description: Time the app was created, as a UTC timestamp in ISO 8601 format.
          example: '2026-08-01T09:15:00'
        updated_date:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Updated Date
          description: >-
            Time the app document was last written, as a UTC timestamp in ISO
            8601 format.
          example: '2026-08-02T14:30:00'
        status:
          anyOf:
            - $ref: '#/components/schemas/AppStatusResponse'
            - type: 'null'
          description: >-
            The app's current build status. Poll while a build is in progress to
            watch it finish. This tracks building, not publishing.
        last_deployed_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Last Deployed At
          description: >-
            Time the app was last published, as a UTC timestamp in ISO 8601
            format, or `null` if it has never been published.
          example: '2026-08-02T14:30:00'
        screenshot_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Screenshot Url
          description: >-
            URL of a screenshot of the published app. Captured shortly after
            each publish, so it can briefly lag or be `null` right after
            publishing.
          example: https://storage.base44.com/screenshots/6820f3a4e7b91d003c45a1f2.png
        preview_screenshot_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Preview Screenshot Url
          description: >-
            URL of a preview screenshot taken before publishing, distinct from
            `screenshot_url`, or `null` if none has been captured.
          example: https://storage.base44.com/previews/6820f3a4e7b91d003c45a1f2.png
      type: object
      title: AppSummary
      description: An app in a workspace, limited to the properties the caller requested.
    FirstPromptModelComparisonState:
      properties:
        id:
          type: string
          title: Id
        client_creation_id:
          type: string
          title: Client Creation Id
        models:
          items:
            type: string
          type: array
          title: Models
        status:
          type: string
          enum:
            - preparing
            - running
            - failed
            - selected
            - cancelled
          title: Status
          default: preparing
      type: object
      required:
        - id
        - client_creation_id
        - models
      title: FirstPromptModelComparisonState
    AppStatusResponse:
      properties:
        state:
          type: string
          enum:
            - ready
            - processing
            - error
          title: State
          description: >-
            Where the app is in its build lifecycle. Ready means idle with no
            build in progress, processing means the app is being generated or
            modified, and error means the last build failed. This tracks
            building, not publishing.
          example: ready
        details:
          anyOf:
            - type: string
            - type: 'null'
          title: Details
          description: >-
            Human readable note about the current state, such as what is being
            processed or why it failed, or `null` when there is nothing to
            report.
          example: Publishing app
        request_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Request Id
          description: >-
            ID of the request that last changed the status, or `null` if the
            status has never changed. Useful when reporting an issue.
          example: a1b2c3d4e5f67890abcdef12
        last_updated_date:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Last Updated Date
          description: >-
            Time the status was last updated, as a UTC timestamp in ISO 8601
            format.
          example: '2026-08-02T14:30:00Z'
        error_source:
          anyOf:
            - type: string
            - type: 'null'
          title: Error Source
          description: >-
            Where the failure originated when `state` is `error`, or `null`
            otherwise. A value of `paywall` means the work was blocked because
            the app's workspace has no credits left.
          example: build
        paywall_context:
          anyOf:
            - $ref: '#/components/schemas/PaywallStatusContextResponse'
            - type: 'null'
          description: >-
            Present when the operation was blocked by a plan limit, describing
            what was evaluated, or `null` otherwise.
      type: object
      required:
        - state
      title: AppStatusResponse
      description: The app's current build status.
    PaywallStatusContextResponse:
      properties:
        billing_organization_id:
          type: string
          title: Billing Organization Id
          description: ID of the billing organization the paywall was evaluated against.
          example: 67e0b12c4d8a3f005b21c9e4
        user_id:
          type: string
          title: User Id
          description: ID of the user the paywall was evaluated for.
          example: 6706af53b9c1e2004a37d85f
        evaluated_at:
          type: string
          format: date-time
          title: Evaluated At
          description: >-
            Time the paywall condition was evaluated, as a UTC timestamp in ISO
            8601 format.
          example: '2026-08-02T14:30:00Z'
      type: object
      required:
        - billing_organization_id
        - user_id
        - evaluated_at
      title: PaywallStatusContextResponse
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: api_key
      description: Personal API key.

````