---
title: "Create entity schema"
method: POST
path: "/api/apps/{app_id}/entity-schemas"
---

# Create entity schema

`POST /api/apps/{app_id}/entity-schemas`

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

## Path parameters

- `app_id` string, required — ID of the app whose entity schemas you want to work with.

## Request body

- CreateEntitySchemaRequest
  - `entity_name` string, required — Name for the new entity. Letters, numbers, and underscores only. Cannot be `User`.
  - `entity_schema` object, required — 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`.

## Response `200`

Successful Response

- EntitySchemaResponse — One of an app's entities and its stored JSON Schema.
  - `entity_name` string, required — Name of the entity.
  - `entity_schema` object, required — 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.

## Other responses

- `400` — 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` — Missing or invalid credentials.
- `403` — You don't have editor access to this app, or your workspace API key lacks the `apps:deploy` scope.
- `404` — App not found.
- `409` — 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` — 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.

---

[API](https://skmtc.dev/adexad/apis/base44-app-management-api.md) · [All operations](https://skmtc.dev/adexad/apis/base44-app-management-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/adexad/base44-app-management-api/revisions/7f5ce8287501/schema)