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



## 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:
  - ApiKeyAuth: []
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.
      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
      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, or the schema sets
            row-level security rules Base44 cannot enforce.
        '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.
        '409':
          description: >-
            The app already has an entity with this name (a workspace API key
            resending a byte-identical schema gets a 200 instead), or the
            request is scoped to a feature branch (entity schemas can only be
            changed on the main branch).
        '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.
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.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: api_key
      description: Personal API key.

````