> ## 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
> This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.
Adds a new entity to the app and makes it queryable right away.
Send the entity name and its JSON Schema. The name must contain only letters, numbers, and underscores. Put the entity's `properties` and `required` fields in `entity_schema`, and its row-level security rules under `rls`. Base44 adds a `name` key holding the entity name to the schema it stores and returns.
This changes the app's live schema right away, but it does not change the entity definition in the app's source code. Base44 rebuilds the live schema from the source files whenever the app's code changes, which reverts anything you set here. Change the code itself when you need the edit to last.
You cannot create `User`, which is built in. Use [Update entity schema](/api-reference/update-entity-schema) with `User` to add custom fields to it.
A name the app already uses returns a 409. The one exception is a workspace API key resending a byte-identical schema, which returns a 200 so a repeated deploy is safe. The same request with a personal API key still returns a 409.
This endpoint accepts a personal API key, or a workspace API key with the `apps:deploy` scope.
## 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: >-
This API is in beta. Endpoints, fields, and behavior may still
change, so avoid depending on it in production.
Adds a new entity to the app and makes it queryable right away.
Send the entity name and its JSON Schema. The name must contain only
letters, numbers, and underscores. Put the entity's `properties` and
`required` fields in `entity_schema`, and its row-level security rules
under `rls`. Base44 adds a `name` key holding the entity name to the
schema it stores and returns.
This changes the app's live schema right away, but it does not
change the entity definition in the app's source code. Base44 rebuilds
the live schema from the source files whenever the app's code changes,
which reverts anything you set here. Change the code itself when you
need the edit to last.
You cannot create `User`, which is built in. Use [Update entity
schema](/api-reference/update-entity-schema) with `User` to add custom
fields to it.
A name the app already uses returns a 409. The one exception is a
workspace API key resending a byte-identical schema, which returns a 200
so a repeated deploy is safe. The same request with a personal API key
still returns a 409.
This endpoint accepts a personal API key, or a workspace API key
with the `apps:deploy` scope.
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.
title: App Id
description: ID of the app whose entity schemas you want.
example: 6820f3a4e7b91d003c45a1f2
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateEntitySchemaRequest'
responses:
'200':
description: The created entity schema.
content:
application/json:
schema:
$ref: '#/components/schemas/EntitySchemaResponse'
'400':
description: >-
`entity_name` is empty or has characters other than letters,
numbers, and underscores; `entity_schema` is not a valid JSON
Schema; `entity_name` is `User`; 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: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
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: its `properties`, its `required` fields,
and any row-level security rules 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. For the app's own entities this
includes a `name` key Base44 sets on every write; the `User` schema
does not get one.
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
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:
ApiKeyAuth:
type: apiKey
in: header
name: api_key
description: Personal API key.
````