> ## 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 entity schema

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

Adds a new entity to the specified app.

This changes the app's live data model, so it takes effect immediately. It doesn't change the file that defines that model in the app's source code. Since Base44 rebuilds the live model whenever the file is written or the app's code is pulled from GitHub, a change made using this endpoint may be reverted.

To change the model for good, change the entities configuration files.

You can't create `User`, which is built in. Use [Update entity schema](/api-reference/update-entity-schema) with `User` to add custom fields to it.

Entity schemas change on main only, so naming a branch in `branch_id` returns a 409. To add entities or fields on a [branch](/developers/references/app-management/get-started/concepts#branches), use [Send chat message](/api-reference/send-chat-message) with that `branch_id`.



## OpenAPI

````yaml /developers/references/app-management/app-management-openapi.json post /api/apps/{app_id}/entity-schemas
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}/entity-schemas:
    post:
      summary: Create entity schema
      description: >-
        <Info>This API is in beta. Endpoints, fields, and behavior may still
        change, so avoid depending on it in production.</Info>


        Adds a new entity to the specified app.


        This changes the app's live data model, so it takes effect immediately.
        It doesn't change the file that defines that model in the app's source
        code. Since Base44 rebuilds the live model whenever the file is written
        or the app's code is pulled from GitHub, a change made using this
        endpoint may be reverted.


        To change the model for good, change the entities configuration files.


        You can't create `User`, which is built in. Use [Update entity
        schema](/api-reference/update-entity-schema) with `User` to add custom
        fields to it.


        Entity schemas change on main only, so naming a branch in `branch_id`
        returns a 409. To add entities or fields on a
        [branch](/developers/references/app-management/get-started/concepts#branches),
        use [Send chat message](/api-reference/send-chat-message) with that
        `branch_id`.
      operationId: create_schema_api_apps__app_id__entity_schemas_post
      parameters:
        - name: app_id
          in: path
          required: true
          schema:
            type: string
            description: ID of the app whose entity schemas you want to work with.
            title: App Id
          description: ID of the app whose entity schemas you want to work with.
          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/CreateEntitySchemaRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntitySchemaResponse'
        '400':
          description: >-
            The `entity_name` is empty, has characters other than letters,
            numbers, and underscores, or is `User`. It also fires when
            `entity_schema` is not a valid JSON Schema, the schema sets
            row-level security rules Base44 cannot enforce, or the schema newly
            declares a keyword Base44 does not implement (such as `unique`).
        '401':
          description: Missing or invalid credentials.
        '403':
          description: >-
            You don't have editor access to this app, or your workspace API key
            lacks the `apps:deploy` scope.
        '404':
          description: App not found, or no branch you can see has this `branch_id`.
        '409':
          description: >-
            The app already has an entity with this name (a workspace API key
            resending a byte-identical schema gets a 200 instead), main is
            protected (`branch_protected`), or `branch_id` names a branch
            (`operation_blocked_on_branch`). The reason for the last two is in
            `extra_data.reason`.
        '422':
          description: >-
            The request body is missing, or `entity_name` or `entity_schema` is
            missing or has the wrong type. Whether `entity_schema` is a usable
            JSON Schema is checked after this and returns a 400. It also fires
            when the entity store rejects a schema it cannot store, such as one
            with an empty property name or a number too large to store. Fix the
            schema and send it again.
        '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:
            - apps:deploy
        - WorkspaceApiKeyBearerAuth:
            - apps:deploy
components:
  schemas:
    CreateEntitySchemaRequest:
      properties:
        entity_name:
          type: string
          title: Entity Name
          description: >-
            Name for the new entity. Letters, numbers, and underscores only.
            Cannot be `User`.
          example: Invoice
        entity_schema:
          additionalProperties: true
          type: object
          title: Entity Schema
          description: >-
            The entity's [JSON
            Schema](/developers/backend/resources/entities/entity-schemas).
            Needs `"type": "object"` and a `properties` object, plus any
            `required` fields and [row-level security
            rules](/developers/backend/resources/entities/security) under `rls`.
          example:
            name: Invoice
            properties:
              amount:
                description: Total amount in cents
                type: number
              status:
                enum:
                  - draft
                  - sent
                  - paid
                type: string
            required:
              - amount
            rls:
              read:
                created_by: '{{user.email}}'
            type: object
      type: object
      required:
        - entity_name
        - entity_schema
      title: CreateEntitySchemaRequest
    EntitySchemaResponse:
      properties:
        entity_name:
          type: string
          title: Entity Name
          description: Name of the entity.
          example: Invoice
        entity_schema:
          additionalProperties: true
          type: object
          title: Entity Schema
          description: >-
            The entity's stored [JSON
            Schema](/developers/backend/resources/entities/entity-schemas),
            including its `properties`, `required` fields, and any [row-level
            security rules](/developers/backend/resources/entities/security)
            under `rls`. For the app's own entities it also carries a `name` key
            holding the entity name. For `User` it holds only the custom fields
            added on top of the built-in ones, and has no `name` key.
          example:
            name: Invoice
            properties:
              amount:
                description: Total amount in cents
                type: number
              status:
                enum:
                  - draft
                  - sent
                  - paid
                type: string
            required:
              - amount
            rls:
              read:
                created_by: '{{user.email}}'
            type: object
      type: object
      required:
        - entity_name
        - entity_schema
      title: EntitySchemaResponse
      description: One of an app's entities and its stored JSON Schema.
    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.
    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.