Entities
Structured schemas with records, search, and the entity tools.
Entities are user-defined structured data: a schema with typed fields, rows of records, and search over them. Think lightweight database tables the platform (and agents, via the five entity tools) can read and write.
Manage schemas at Entities: list, detail (Entity Information and Entity Data tabs), edit, and per-record views.
Schemas
A schema has a name, an optional description, and a list of fields. The
name uses letters, digits, and underscores, can't start with a digit, is
unique, and can't change after creation. Schemas also carry
record access rules and hooks.
Each field has a name (same rule, unique within the schema), a type, and optional requiredness, default, allowed values, description, and search indexes.
| Type | Accepts |
|---|---|
integer, float | Numbers (integer must be whole) |
string | Text |
email, url | A valid address, an absolute URL |
boolean | true or false |
date, datetime | A parseable date string |
array | A list; items take one non-array type (default string) |
Every write is checked against the schema. Empty values count as absent. Defaults fill absent fields on create. Required fields must be present on create, and an update can't clear one. Allowed values restrict scalar fields.
Records
Records hang off the schema name (not id) — every record read resolves
the schema first. Each record carries system fields (id, owner,
createdBy, createdAt, updatedAt) plus its data. The owner is always the
user who created the record, never a value from the data.
GET /entities/:id/records serves both paging and search from one URL. Without
q it lists records (default 100, max 500). With q it searches them
(default 20, max 100), taking mode, scoreThreshold, and fields.
Search
Each field opts into a full-text index, a vector index, or both. The form
offers vector indexing on string, email, and url fields. Search modes
follow what's indexed:
| Mode | Needs |
|---|---|
keyword (default) | At least one full-text field |
vector | At least one vector field |
hybrid | Both |
fields narrows a search to some indexed fields; when those fields don't
cover the chosen mode, the search returns nothing. A failed vector or hybrid
search falls back to keyword.
The Entity Data tab loads the first 100 records and searches with keyword (or the first mode available), 20 results, and a 0.65 score threshold. If search fails there, it retries keyword, then filters the loaded rows locally and says so.
Entity Settings
One setting, behind the gear on the Entities page: the embedding model for
every vector field on every entity. The default is text-embedding-3-small;
the Free plan embeds with FastEmbed (BAAI/bge-large-en-v1.5) only. Index
dimensions follow the model. After changing it, re-save each entity schema to
rebuild its index; records re-embed on their next update.
Record access
Off by default. When on, each role gets a level:
| Level | Sees and changes |
|---|---|
public | Every record |
private | Only records they own |
none | Nothing — reads, lists, searches, updates, deletes, and creates are all refused |
Admins default to public. Everyone else — members, guests, custom roles —
takes the member level, default private. The organization owner always has
full access. Rules apply everywhere records are touched: the UI, the REST
API, and the entity tools, which act as the chatting user.
Hooks
beforeExecute and afterExecute run on create, update, and delete — not on
reads — in the same sandbox as function tools. Each is a
function of that name taking (data, runtime).
| Hook | data | Returning an object |
|---|---|---|
beforeExecute | The incoming record data; on delete, { id, record } | Replaces the data before validation (create, update) |
afterExecute | The saved record; on delete, { id, deleted: true } | Replaces the response (create, update) |
runtime holds operation (create, update, or delete), user,
tenantId, entityId, entityName, and recordId once the record exists.
A hook may add fields the schema doesn't declare; they are stored with the
record.
Hooks fail open: an error, a return over 128 KB, or an unavailable sandbox skips the hook and the write goes ahead unchanged.
Entity tools
Five tools give agents records: create_record, read_record,
update_record, delete_record, and list_records. Each is configured with
one or more entities, and the model sees one tool per entity, named
<tool>_<entity> with the entity name lowercased — list_records_customer,
for example. Tool inputs are built from the entity's fields; the tool keeps a
snapshot of them, so reselect the entity after changing its schema.
| Tool | Model inputs | Returns |
|---|---|---|
create_record | data — writable fields, required ones required | The new record |
read_record | id | The record |
update_record | id, data — at least one writable field | The updated record |
delete_record | id | { success, id } |
list_records | filters (exact match on filterable fields), limit, skip | items and total |
list_records filters only; it does not search.
| Option | Tools | Default | Effect |
|---|---|---|---|
writableFields | create, update | all fields | Fields the model may set. |
defaults | create | none | Values for writable fields the model leaves out. |
readableFields | all but delete | all fields | Fields returned. id, entityId, tenantId, createdAt, and updatedAt are always included. |
filterableFields | list | all fields | Fields filters may use. |
defaultLimit | list | 20 | Records when the model gives no limit. |
maxLimit | list | 100 | Cap on limit; never above 100. |
The tool form picks the entities and, for list_records, the two limits. The
field options have no form yet; set them through the API. Approvals and
before/after hooks work as on any other tool, on top of the
schema's own hooks.