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

> ## Agent Instructions
> Internal links on these pages omit the .md extension. Append .md to a docs page URL, or send an Accept: text/markdown header, to get that page as markdown.

# Create app folder

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

Creates a folder for builder apps or agents.

You can change your own personal folders. Workspace folders need the editor role or higher, and any editor can change any workspace folder. A workspace holds up to 500 folders of both kinds, counting every member's personal folders, and a folder can have at most 20 folders above it. Folder names don't have to be unique, so retrying a create that timed out can leave you with two folders.

This is limited to 60 requests per minute, shared with the other endpoints that change folders. A signed-in session has its own limit, and every personal access token for the workspace shares one. Some workspaces have a different limit.

<Note>Call this with a personal access token sent as a Bearer token, or from a signed-in session. A token works on its own workspace's folders. Workspace API keys aren't accepted, and a read-only token 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.</Warning>



## OpenAPI

````yaml /developers/references/app-management/app-management-openapi.json post /api/app-folders
openapi: 3.1.0
info:
  title: Base44 App Management API
  version: 1.0.0
servers:
  - url: https://app.base44.com
security:
  - PersonalAccessTokenAuth: []
paths:
  /api/app-folders:
    post:
      summary: Create app folder
      description: >-
        <Info>This API is in beta. Endpoints, fields, and behavior may still
        change, so avoid depending on it in production.</Info>


        Creates a folder for builder apps or agents.


        You can change your own personal folders. Workspace folders need the
        editor role or higher, and any editor can change any workspace folder. A
        workspace holds up to 500 folders of both kinds, counting every member's
        personal folders, and a folder can have at most 20 folders above it.
        Folder names don't have to be unique, so retrying a create that timed
        out can leave you with two folders.


        This is limited to 60 requests per minute, shared with the other
        endpoints that change folders. A signed-in session has its own limit,
        and every personal access token for the workspace shares one. Some
        workspaces have a different limit.


        <Note>Call this with a personal access token sent as a Bearer token, or
        from a signed-in session. A token works on its own workspace's folders.
        Workspace API keys aren't accepted, and a read-only token 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.</Warning>
      operationId: api_create_api_app_folders_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAppFolderRequest'
        required: true
      responses:
        '200':
          description: The new folder.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppFolderSummary'
        '400':
          description: >-
            `app_type` isn't `user_app` or `user_agent`, the parent has a
            different `scope` or `app_type` or is another user's personal
            folder, the folder would have more than 20 folders above it, or the
            workspace already has 500 folders.
        '401':
          description: Missing or invalid credentials.
        '403':
          description: >-
            `scope` is `workspace` and you're a viewer or guest, or your token
            is read-only.
        '404':
          description: The parent folder doesn't exist.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Rate limit exceeded.
components:
  schemas:
    CreateAppFolderRequest:
      properties:
        name:
          type: string
          maxLength: 100
          minLength: 1
          title: Name
          description: >-
            Name of the folder, 1 to 100 characters. Names don't have to be
            unique.
          example: Client projects
        scope:
          type: string
          enum:
            - workspace
            - personal
          title: Scope
          description: >-
            `workspace` for a folder every member of the workspace sees, or
            `personal` for one only you see.
          example: workspace
        parent_folder_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Parent Folder Id
          description: >-
            ID of the folder to create this one in, or `null` for a top-level
            folder. The parent must have the same `scope` and `app_type`, and a
            personal parent must be yours.
          example: 68c1f27eb4e7d3005a2c9e0f
        position:
          type: number
          title: Position
          description: Sort key among folders. Lower values come first.
          default: 0
          example: 2
        color:
          anyOf:
            - type: string
              maxLength: 32
            - type: 'null'
          title: Color
          description: Color for the folder, up to 32 characters, such as a hex color.
          example: '#3B82F6'
        icon:
          anyOf:
            - type: string
              maxLength: 64
            - type: 'null'
          title: Icon
          description: Icon name for the folder, up to 64 characters.
          example: briefcase
        app_type:
          anyOf:
            - type: string
              enum:
                - user_app
                - user_agent
            - type: 'null'
          title: App Type
          description: >-
            `user_app` for a folder of builder apps, or `user_agent` for a
            folder of agents. Defaults to `user_app`.
          example: user_app
      type: object
      required:
        - name
        - scope
      title: CreateAppFolderRequest
    AppFolderSummary:
      properties:
        id:
          type: string
          title: Id
          description: ID of the folder.
          example: 68c1f2a9b4e7d3005a2c9e11
        name:
          type: string
          title: Name
          description: Name of the folder.
          example: Client projects
        parent_folder_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Parent Folder Id
          description: ID of the folder this one sits in, or `null` for a top-level folder.
          example: 68c1f27eb4e7d3005a2c9e0f
        scope:
          type: string
          enum:
            - workspace
            - personal
          title: Scope
          description: >-
            `workspace` for a folder every member of the workspace sees, or
            `personal` for one only you see.
          example: workspace
        position:
          type: number
          title: Position
          description: Sort key among folders. Lower values come first.
          example: 2
        color:
          anyOf:
            - type: string
            - type: 'null'
          title: Color
          description: Color set on the folder, or `null` when none is set.
          example: '#3B82F6'
        icon:
          anyOf:
            - type: string
            - type: 'null'
          title: Icon
          description: Icon name set on the folder, or `null` when none is set.
          example: briefcase
        app_type:
          anyOf:
            - type: string
              enum:
                - user_app
                - user_agent
            - type: 'null'
          title: App Type
          description: >-
            `user_app` for a folder of builder apps, or `user_agent` for a
            folder of agents. Builder app folders created before agent folders
            existed leave it out.
          example: user_app
        created_date:
          type: string
          format: date-time
          title: Created Date
          description: >-
            Time the folder was created, in UTC, as an ISO 8601 timestamp
            without a time zone offset.
          example: '2026-08-01T09:15:00'
      type: object
      required:
        - id
        - name
        - parent_folder_id
        - scope
        - position
        - created_date
      title: AppFolderSummary
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    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
  securitySchemes:
    PersonalAccessTokenAuth:
      type: http
      scheme: bearer
      description: 'Personal access token, sent as `Authorization: Bearer <token>`.'

````

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