Skip to main content
An entity is a table in your app’s database. Its schema is a JSON Schema that names the entity’s fields, marks which are required, and holds its row-level security rules under rls. The entity endpoints let you read and change those schemas, read and change the records they hold, and count the records and users an app holds. Use these endpoints to:
  • Read an app’s entity schemas, one at a time or all together.
  • Add, replace, or remove an entity.
  • Make an app’s live data model match its source in one call. This one is limited to apps whose source code you manage yourself.
  • Read, add, change, or remove an entity’s records.
  • Count an entity’s records, or the app’s users.

​
Schema writes don’t change your code

Every write here changes the app’s live data model, so it takes effect immediately. It doesn’t change the entities configuration file that defines that model in the app’s source code, at base44/entities/<EntityName>.jsonc. Base44 rebuilds the live model from those files whenever one of them is written or the app’s code is pulled from GitHub, so a change made only through this API is reverted at that point. To change the model for good, change the file. If the app is connected to a GitHub repository, commit the change there and call Pull changes from GitHub, which rebuilds the live model from your file. Otherwise ask the AI to add or edit the entity with Send chat message, which writes the file the same way the Base44 online app editor does. That makes the write endpoints a good fit for pushing a schema Base44 should serve right now, and a poor fit for a lasting schema edit.

​
The User entity

User is built in, so it doesn’t behave like an entity you defined:
  • You can’t create it. Use Update entity schema with User to add custom fields to it, which also creates those fields the first time.
  • Reading it returns only the custom fields you added, not the built-in ones, and returns a 404 when there are none.
  • Custom fields can’t redeclare email or full_name, which Base44 manages.
  • Its stored schema carries no name key, unlike the schema of an entity you defined.
  • Counting users has its own endpoint, Count app users. Don’t pass User to Count entity records.
  • The record endpoints don’t reject it either. List, Create, Get, Update, and Delete entity record all accept User as an entity_name, but they read and write a separate, disconnected set of records stored under that name, not the app’s real user accounts.

​
Filtering, sorting, and paging

List entity records accepts these query parameters.

​
Filter

Two ways to filter:
  • Pass one of the entity’s own field names directly as a query parameter, for an exact match. ?status=paid matches records where status is "paid".
  • Pass q as a JSON object, for anything beyond an exact match, for example {"amount": {"$gt": 100}}. q accepts:
    • Compare: $eq, $ne, $gt, $gte, $lt, $lte
    • Match a set: $in, $nin
    • Combine conditions: $and, $or, $nor, $not
    • Check presence or type: $exists, $type
    • Arrays: $all, $elemMatch, $size
    • Substring or pattern: $regex
    • Geospatial and full-text, if the field actually holds that kind of data: $near, $nearSphere, $geoIntersects, $geoWithin, $text, $search
A query parameter that isn’t q, limit, skip, sort, or fields, and isn’t one of the entity’s own field names, is still read as a filter on that name. A misspelled field name matches nothing rather than returning an error. Base44 wraps every filter in the entity’s own row-level-security conditions before checking nesting depth, so how deep you can nest q depends on the entity’s rls rules.

​
Sort

Sort with a single field name in sort, prefixed with - for descending, for example -created_date. Sorting by more than one field isn’t supported.

​
Page

Page with limit (1 to 5000, defaults to 5000) and skip (defaults to 0). Base44 caps every call at 5000 records, whether you leave limit out or ask for more, and the response doesn’t indicate when it was cut short.

​
Select fields

Reduce the response size with fields, a comma-separated list of field names. Reach into an object with dots, as in customer.email. Every record still carries its id.

​
Rate limits

Each entity endpoint states its base rate limit in its 429 response. List entity records and Count entity records share one allowance, scoped to one app rather than shared across the workspace’s other apps, and also drawn down by version-history activity in the Base44 online app editor. A paid plan gets a multiple of the base number. See Rate limits for the multiplier table.