---
title: "Update entity schema"
method: PUT
path: "/api/apps/{app_id}/entity-schemas/{entity_name}"
---

# Update entity schema

`PUT /api/apps/{app_id}/entity-schemas/{entity_name}`

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

Replaces an entity's JSON Schema with the one you send. This is a full replacement, not a merge. Anything you leave out is dropped from the schema.

`entity_schema` must be a JSON Schema object, so it needs `"type": "object"` and a `properties` object. Put 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>

Pass `User` as the `entity_name` to set the custom fields on the built-in user entity. Those custom fields cannot redeclare `email` or `full_name`, which Base44 manages. `User` is also the one name this endpoint creates when it does not exist yet. Every other unknown name returns a 404.

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

## Path parameters

- `entity_name` string, required — Name of the entity to replace, as returned by [List entity schemas](/api-reference/list-entity-schemas). Pass `User` to set the built-in user entity's custom fields.
- `app_id` string, required — ID of the app whose entity schemas you want.

## Request body

- UpdateEntitySchemaRequest
  - `entity_schema` object, required — The entity's full JSON Schema, replacing the stored one. Needs `"type": "object"` and a `properties` object, plus any `required` fields and row-level security rules 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. 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` — The `entity_schema` is not a valid JSON Schema, the `User` schema redeclares `email` or `full_name`, 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, or the app has no entity with this name (`User` is created instead of returning a 404).
- `409` — 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/:entity_name/put.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/394136a6cdd4/schema)