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

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

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.

<Note>This endpoint accepts a personal API key, or a workspace API key with the `apps:deploy` scope.</Note>

## Path parameters

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

## 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: its `properties`, its `required` fields, and any row-level security rules under `rls`.

## Response `200`

The created entity schema.

- EntitySchemaResponse
  - `entity_name` string, required — Name of the entity.
  - `entity_schema` object, required — 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.

## Other responses

- `400` — `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` — 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` — Validation Error

## Changes

- **2026-08-25** `8dfd9c46c0b9` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/idealspot/apis/base44-app-management-api/changes/api/apps/:app_id/entity-schemas/post.md)

---

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